모드 (API): Advanced Use Guide

2024년 06월 05일 07:00

스크립트 편집기

게임 스크립트를 편집하려면 게임 세부 정보 페이지에서 "Mod (API) 스크립트" 링크를 클릭하십시오 ("채팅 로그" 및 "게임 복사/확장"과 같은 옵션이 있는 곳). 여러 가지 기능이 제공됩니다:

위쪽에 탭 목록이 표시됩니다. 게임은 쉬운 조직을 위해 여러 개의 스크립트를 가질 수 있습니다. 모든 스크립트는 여전히 동일한 컨텍스트에서 실행되므로 동시에 동일한 값을 덮어쓰려고 하는 여러 스크립트가 있으면 의도하지 않은 결과가 발생할 수 있습니다.
스크립트 코드 편집기입니다. 이 편집기를 사용하거나 선택한 외부 편집기에서 스크립트를 편집한 다음 여기에 붙여넣을 수 있습니다.
하단에 위치한 "Mod (API) 콘솔"(아래 참조).

"스크립트 저장" 버튼을 클릭할 때마다 게임의 샌드박스가 재시작됩니다 (롤백됨) (메모리에 저장되지 않은 데이터는상태개체 또는 Roll20 개체에 저장되지 않은 경우). 이는 새 스크립트를 추가하거나 스크립트를 삭제하거나 스크립트를 활성화/비활성화하는 경우에도 적용됩니다.

Mod (API) 콘솔

Mod (API) 콘솔은 귀하의 스크립트로의 창입니다. Mod (API) 스크립트가 샌드박스에서 실행되므로 실행 중에는 직접 액세스할 수 없어 스크립트 결과 또는 오류에 대한 정보를 볼 수 없습니다. Mod (API) 콘솔은 샌드박스 밖에서 이 정보를 표시하여 스크립트를 편집하는 동안 볼 수 있습니다. 모든 log() 명령은 여기에 나타나며, 스크립트 실행 중에 발생한 모든 오류도 표시됩니다. 자세한 정보는 디버깅 스크립트에 대한 기사를 참조하십시오..

반응형 스크립트: 이벤트 수신, 객체 수정

Mod (API) 사용의 첫 번째(가장 간단한 유형)은 테이블탑에서 변경 사항에 반응하고, 변경된 객체에 대해 추가 기능으로 응답하는 것입니다. 이 유형의 스크립트는 게임 중 발생하는 이벤트를 수신하는 여러 함수로 구성됩니다. 그런 다음 해당 이벤트 중 전달된 객체를 수정하여 테이블탑에서 발생하는 일을 변경합니다.

기본 스크립트는 조각을 5피트(기본 페이지 설정을 기준으로 가정) 추가로 이동시킬 것입니다.


        on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + 70    
  });
});

As you can see, we created a simple on function using which will be executed anytime the change:graphic event is heard. The function is passed the graphic object, obj. To make a change, we just modify obj using the set function -- whatever properties we change will be detected and changed on the tabletop.

You must usesetandgetto set and get current values on objects or your changes will not be saved. (See below for a listing of object types and their properties, as well as a listing of all events and what arguments each event is passed.)

A Note on Utility Functions

Of course, the previous example isn't incredibly helpful because it always adds 70 pixels to the location of the token. But what if the user has changed their scale so that 5ft is 140 pixels? The Roll20 API provides several handy utility functions to help with this (and other) common scenarios. 이전 예제를 수정하여 테이블 상판의 "5피트"(또는 인치, 미터 또는 설정된 다른 거리 유형)가 몇 픽셀인지 알려주는distanceToPixelsfunction을 사용해 보겠습니다.

on("change:graphic", function(obj) {    
  obj.set({        
    left: obj.get("left") + distanceToPixels(5);    
  });
});

현재 페이지가 기본 그리드 크기를 사용하도록 설정된 경우distanceToPixels(5);은 여전히 70픽셀을 반환하지만, 페이지의 배율이 일반 크기의 두 배로 설정된 경우 140픽셀을 반환합니다.

페이지나 토큰의 설정이 변경되어도 스크립트가 깨지지 않도록 도와주는 유틸리티 함수를 사용하는 것은 항상 좋은 생각입니다.

적극적인 스크립트: 사용자 개입 없이 작업 수행

사용자 이벤트에 반응하는 것 외에도, API를 사용하여 특정 플레이어 이벤트에 연결되지 않은 작업을 자동으로 수행할 수 있습니다. 예를 들어, 지도에서 왕복으로 순찰하는 토큰을 만들어 보겠습니다.

참고: 이 유형의 스크립트는 사용자 상호 작용에 의존하지 않지만, 귀하의 게임을 위한 Mod (API) 스크립트는 게임에 연결된 한 명 이상의 사용자가 있을 때에만 실행됩니다.

on("ready", function() {
   //게임이 완전히 로드된 것을 알기 위해 ready 이벤트가 발생할 때까지 기다립니다.
   //패트롤 토큰에 대한 참조를 가져옵니다.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //게임에 "Guard A"라는 이름의 토큰이 있다는 것을 알고 있습니다.
   var direction = -1*distanceToPixels(5); //왼쪽으로 70픽셀 이동합니다.
   var stepstaken = 0; //현재 방향으로 몇 걸음을 걸었는지 기록합니다.
   setInterval(function() {
     if(stepstaken > 3) {
       //방향을 바꿉니다!
       direction = direction * -1; //걷는 방향을 "뒤집습니다"
       stepstaken = 0; //걸음 수를 0으로 초기화합니다.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //걷기!
     stepstaken++;
   }, 5000); //5초마다 한 번씩 동작합니다
});

비동기 함수에 대한 논문

비동기 함수는 호출하는 범위로 즉시 제어 스레드를 반환하고 백그라운드에서 일부 작업을 수행하는 함수입니다. 다음은 Mod (API) 스크립트 탭에 붙여 넣을 수 있는 매우 간단하고 이해하기 쉬운 예제입니다:

on('load',function(){
  log('부모 범위 - 비동기 함수 호출 전.');

  setTimeout(function(){
    log('비동기 함수 범위 - 비동기 함수 작업 수행.');
  },10 /* 10 밀리초 */);

  log('부모 범위 - 비동기 함수 호출 후.');
});

Mod (API) 로그에서는 다음과 같은 내용을 볼 수 있습니다:

"부모 범위 - 비동기 함수 호출 전."
"부모 범위 - 비동기 함수 호출 후."
"비동기 함수 범위 - 비동기 함수 작업 수행."

그 코드를 보면 "당연히 나중에 일어날 거야, 10 밀리초 후에 실행하라고 했잖아?"라고 생각합니다. 다음은 같은 로그 메시지를 가지는 덜 명확한 예제입니다:

on('load',function(){
  log('부모 범위 - 비동기 함수 호출 전.');

  sendChat('비동기 함수','이걸 평가해봐: [[1d6]]',function(msg){
    log('비동기 함수 범위 - 비동기 함수 작업 수행.');
  });

  log('부모 범위 - 비동기 함수 호출 후.');

비동기 함수는 API가 항상 멈추는 것을 방지하기 위해 필요합니다. 만약 모든 주사위 굴림이 동기적으로 처리되었다면, API는 매우 느리고 응답성이 없을 것입니다. 콜백을 사용하는 거의 모든 함수는 비동기적입니다. (_.map, _.reduce 등의 일부 함수는 이에 예외이며, 이는 대부분의 사람들이 익숙한 절차적 프로그래밍과는 대조적인 함수형 프로그래밍의 예입니다.)