모드 스크립트: 유틸리티 함수

2026년 09월 28일 14:52

Roll20 게임 공간을 일관성 있게 활용할 수 있도록 돕는 유틸리티 함수들이 제공됩니다. 스크립트의 어느 곳에서나 (예를 들어, 어떤 이벤트 콜백 내부에서도) 유틸리티 함수를 호출할 수 있습니다. 전체 함수 참조 내용은 ‘Mod Scripts: 함수 문서’에서 확인할 수 있습니다.

언더스코어.js

작업을 더 쉽게 할 수 있도록 Underscore.js 라이브러리( _ 전역 객체를 통해)를 사용할 수 있습니다. Underscore는 _.each (객체 배열을 순회하기 위한)와 같은 헬퍼 함수를 제공합니다. 자세한 내용은 Underscore 문서를 참고하세요.

벌목

`log(메시지)`

이 기능을 사용하면 스크립트 편집기 페이지의 Mod 출력 콘솔에 출력을 기록할 수 있습니다. 스크립트를 디버깅하고 모드 스크립트 샌드박스 내부에서 어떤 일이 일어나고 있는지 더 잘 파악하는 데 유용합니다.

on("change:graphic", function(obj) {
  log("객체 ID: " + obj.id 변경 감지됨);
});

Mod Script 샌드박스 v1.5 전용입니다. 가능한 경우, 오류 메시지에는 관련된 Roll20 객체의 이름을 나타내는 컨텍스트 객체가 포함됩니다. 예를 들어:

오류: toBelow() 함수는 Roll20 그래픽, 텍스트 또는 경로 객체를 인수로 받아 호출되어야 합니다. [Roll20 캐릭터 -NM0tVij02hIfnoTdihc]로 호출되었습니다.

객체 정렬

`toFront(obj)` 및 `toBack(obj)`

이 두 가지 기능은 테이블탑 위에 있는 개체를 현재 속해 있는 레이어의 앞쪽(또는 뒤쪽)으로 이동시킵니다. 이때, 이벤트 콜백을 통해 수신하거나 getObj 또는 findObjs를 호출하여 얻은 것과 같은 실제 객체를 반드시 전달해야 한다는 점에 유의하십시오.

`toAbove(obj, target)` 및 `toBelow(obj, target)`

Mod Script 샌드박스 v1.5 전용입니다. 스택 순서상 obj를 target의 바로 위나 바로 아래에 배치합니다. 대상에는 그래픽, 텍스트, 경로, pathv2 객체 또는 해당 객체의 ID가 포함될 수 있습니다. toFront 와 toBack은 객체 자체를 매개변수로 받습니다. 이러한 유형들에는 toFront(), toBack(), toAbove(target), toBelow(target)과 같은 인스턴스 메서드도 있습니다.

난수

`랜덤 정수(최대값)`

Roll20 주사위와 동일한 생성기를 사용하여 1부터 max까지의 범위에서 무작위 정수를 반환합니다. 이건 주사위용으로 쓰세요. Math.floor(Math.random() * max) + 1은 사람들이 실제로 굴리는 주사위의 크기에 대해 균등하게 분포됩니다. 모듈로 편향은 별개의 문제입니다 (정수 % n).

`Math.random()`

모드 스크립트에서 평소와 같이 Math.random() 을 호출해도 결과가 무작위일 것이라고 믿어도 됩니다. 자바스크립트의 “기본” Math.random() 은 Roll20을 구동하는 암호학적으로 안전한 PRNG로 대체되었기 때문입니다. 따라서 Math.random() 을 사용하는 기존 스크립트는 그 결과가 컴퓨터에서 얻을 수 있는 한 최대한 무작위에 가깝다는 점을 염두에 두고 그대로 사용할 수 있습니다.

주사위 굴리기에는 randomInteger(max)를 사용하는 것이 좋습니다. 이것은 주사위 엔진이 사용하는 것과 동일한 생성기입니다.

플레이어가 GM입니다

`플레이어가GM인가(플레이어ID)`

해당 플레이어가 현재 GM인지 여부를 반환합니다. 재시작 없이 승격 및 “플레이어로 재가입” 절차가 이어집니다. playerIsGM("API") 가 false입니다: 스크립트를 통해 전송된 채팅이 게임 내 플레이어가 아닌 "API"라는 플레이어 ID를 사용하고 있습니다.

캐릭터

`setDefaultTokenForCharacter(캐릭터, 토큰)`

제공된 캐릭터 객체의 기본 토큰을 제공된 토큰 객체의 세부 정보로 설정합니다. 두 개체 모두 이미 존재해야 합니다. 이것은 현재 캐릭터에 연결된 기본 토큰을 덮어쓸 것입니다.

시각 효과 (FX)

`spawnFx(x, y, type, pageid)`

x,y 좌표의 위치에 해당 유형의 짧은 효과를 생성합니다. pageid를 생략하거나 undefined를 전달하면, 기본적으로 플레이어가 현재 있는 페이지(Campaign 객체의playerpageid )가 사용됩니다.

내장 효과의 경우, 유형은 문자열이어야 하며 다음 중 하나여야 합니다: beam-color, bomb-color, breath-color, bubbling-color, burn-color, burst-color, explode-color, glow-color, missile-color, nova-color, splatter-color

여기서 ‘색’은 다음 중 하나를 의미한다: 산, 피, 매력, 죽음, 불, 서리, 신성, 마법, 슬라임, 연기, 물

사용자 지정 효과의 경우, type에는 해당 사용자 지정 효과에 대한 custfx 객체의 ID를 입력해야 합니다.

`spawnFxBetweenPoints(점1, 점2, 유형, 페이지ID)`

spawnFx와 동일하게 작동하지만, 단일 좌표 대신 {x: 100, y: 100} 형식으로 두 개의 좌표를 전달합니다. 예를 들어: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"). 광선, 호흡, 그리고 튀는 효과가 두 지점 사이를 오간다. 좌표는 페이지 픽셀 단위로, 그래픽과 동일한왼쪽/위쪽 여백을 나타냅니다. 창과 문의x/y 좌표는 반전된 축을 사용하므로, 이 좌표들과는 다릅니다.

다음 효과 유형은 항상 spawnFx 대신 spawnFxBetweenPoints를 사용해야 합니다: beam-color, breath-color, splatter-color

Mod Script 샌드박스 v1.5 전용입니다. 빔형 효과가 point2를 직접 가리킵니다(각도 계산 오류가 수정되었습니다).

`spawnFxWithDefinition(x, y, definition, pageid)`

x, y 위치에 임시 사용자 정의 효과를 생성합니다. 정의는 JSON 문자열이 아니라 자바스크립트 객체입니다. 이 형식은 Custom FX 정의와 동일합니다. pageid를 생략하거나 undefined를 전달하면 플레이어의 현재 페이지(Campaign().get("playerpageid"))가 사용됩니다.

주크박스 재생 목록

`playJukeboxPlaylist(playlistid)`

재생 목록의 폴더 ID(캠페인 객체의 _jukeboxfolder 속성에서 가져옴)를 받아, 게임에 참여 중인 모든 플레이어에게 해당 재생 목록을 재생하기 시작합니다.

`stopJukeboxPlaylist()`

인수를 필요로 하지 않으며, 현재 재생 중인 모든 재생 목록을 중지합니다.

기타

`sendPing(left, top, pageid, playerid, moveAll, visibleTo)`

테이블탑에 핑을 보냅니다(마우스 버튼을 누르고 있는 것과 동일합니다). 왼쪽과 위쪽은 페이지 픽셀입니다. pageid를 입력해야 합니다. playerid는 선택 사항이며 네 번째 인수로, 핑이 발생한 플레이어를 나타냅니다. 이를 생략하거나 거짓값을 전달하면 핑은 “api” (노란색)의 속성으로 기록됩니다.

moveAll에 true를 전달하면 플레이어들을 해당 지점으로 스크롤합니다. visibleTo는 핑을 볼 수 있는 대상을 제한합니다: 플레이어 ID 하나, ID 배열, 또는 쉼표로 구분된 문자열. 이 부분을 생략하거나 ""을 전달하면 모든 사용자에게 알림을 보냅니다.

아래 예시에서 setTimeout으로 설정된 지연 시간은 샌드박스가 재시작되면 초기화됩니다.

on("채팅:message", function(msg) {
  if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
  var players = findObjs({_type: "player"});
  if (players.length < 1) return;
  var player1 = players[0].id;
  var player2 = players.length > 1 ? players[1].id : player1;
  var allPlayerIDs = players.map(function(player) { return player.id; });
  var pageid = Campaign().get("playerpageid");
  // pageid는 세 번째 인자이고, playerid는 네 번째 인자입니다. null은 ping의 속성을 "api"로 지정합니다.
  sendPing(300, 300, pageid, null, true);
  setTimeout(function() {
    // visibleTo에 ""를 지정하면 모든 사용자에게 핑이 전송됩니다.
    sendPing(1500, 500, pageid, msg.playerid, true, "");
  }, 1000);
  setTimeout(function() {
    sendPing(1200, 500, pageid, null, true, player1);
  }, 2000);
  setTimeout(function() {
    sendPing(900, 100, pageid, player2, true, [player1, player2]);
  }, 3000);
  setTimeout(function() {
    sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
  }, 4000);
});

Roll20에서의 거리와 격자에 관한 참고 사항

정사각형 격자에서 1단위는 70픽셀입니다. 이 페이지에서 snapping_increment는 각 격자 공간의 단위 수를 나타내며, scale_number는 1단위의 거리이고, scale_units는 단위명(대개 ft)입니다. 기본값은 1 단위 = 5 피트 = 1 제곱 = 70 픽셀입니다. GM은 1 단위를 10피트로 설정하거나, 각 사각형을 2 단위(140 픽셀)로 설정할 수 있습니다.

육각형 격자에서는 그 70픽셀 크기의 정사각형을 사용하지 않습니다. 창과 문의 위치는 y축이 반전된 좌표계를 사용하지만, 그래픽의왼쪽/위쪽은 그렇지 않습니다.