API: 유틸리티 함수

2025년 11월 07일 18:32

언더스코어.js

Underscore.js 라이브러리를 (_전역 객체를 통해) 사용할 수 있어 작업을 더 쉽게 할 수 있습니다. Underscore는 객체 배열을 반복 처리하는_.each와같은 작업을 위한 헬퍼 함수를 제공합니다. 언더스코어 문서를 확인해 보세요. 언더스코어 문서 자세한 내용은

벌목

log(메시지)

이 기능을 사용하여 스크립트 편집기 페이지의 모듈(API) 콘솔에 출력을 기록할 수 있습니다. 스크립트 디버깅에 유용하며, 모드(API) 샌드박스 내부에서 발생하는 상황을 더 잘 파악할 수 있습니다.

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

객체 정렬

toFront(obj)및toBack(obj)

이 두 기능은 테이블탑 위의 개체를 현재 위치한 레이어의 앞쪽(또는 뒤쪽)으로 이동시킵니다. 실제 객체를 전달해야 한다는 점에 유의하십시오. 예를 들어 이벤트 콜백에서 수신한 객체나getObj또는findObjs 호출을 통해 얻은 객체 등이 해당됩니다.

난수

랜덤 정수(최대값)

이 기능을 주사위에 사용하세요! 이 함수는 모듈로 바이어스 을 고려하여 결과 난수가 1과 MAX 사이에서 균등하게 분포되도록 보장합니다.

최소값이 1이고 최대값이max인 임의의 정수를 반환합니다. 이 기능은 Roll20이 주사위 굴림을 구현하는 데 사용하는 것과 동일하며, 이 숫자들은 통계적으로 엄격하게 무작위임이 입증되었습니다.

Math.random()

Mod(API) 스크립트에서 Math.random()을 평소처럼 호출할 수 있으며, 결과가 무작위일 것이라고 믿어도 됩니다. 자바스크립트의 "기본" Math.random()이 Roll20을 구동하는 암호학적으로 안전한 PRNG로 대체되었기 때문입니다. 따라서 Math.random()을 사용하는 기존 스크립트는 결과가 컴퓨터에서 얻을 수 있는 최대한 무작위에 가깝다는 점을 인지한 상태로 사용할 수 있습니다.

범위 내 숫자의 균등 분포가 필요한 경우 Math.random()을 사용하지 마십시오. Math.random()은 Roll20이 처리할 수 있는 수준에서 충분히 우수한 난수를 제공하지만, 그 난수를 주사위 굴림처럼 균일한 분포를 가진 범위로 변환하는 수학적 처리는 모듈로 연산이나 바닥 함수 호출을 통한 곱셈만큼 간단하지 않습니다. 해당 경우에는randomInteger(max)를사용하십시오.

플레이어가 GM입니다

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

플레이어는 GM 기능은 게임 내 플레이어가 GM인지 여부에 대한 부울 값을 반환합니다. 해당 함수는 항상 현재 시점에 따라 올바른 결과를 반환하므로, 게임 진행 중 GM이 플레이어로 재가입하거나 플레이어가 GM으로 승격되는 경우에도 playerIsGM()은 캐시를 지우거나 Mod(API) 샌드박스를 재시작할 필요 없이 상황에 맞게 반응합니다.

캐릭터

문자에 대한 기본 토큰 설정(캐릭터, 토큰)

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

시각 효과 (FX)

spawnFx(x, y, type, pageid)

x,y 위치에 유형의 짧은 효과를 생성합니다. 페이지id를 생략하거나 'undefined'를 전달하면, 플레이어가 현재 위치한 페이지(캠페인 객체의 'playerpageid')가 기본값으로 사용됩니다.

내장 효과의 경우 유형은 문자열이어야 하며 다음 중 하나여야 합니다:빔 색상,폭탄 색상,숨결 색상,거품 색상,화상 색상,폭발 색상, 분출 색상,발광 색상,미사일 색상,신성 폭발 색상,튀김 색상

위에서 "색"은 다음 중 하나를 가리킵니다:산성,피,매력,죽음,불,서리,신성,마법,슬라임,연기,물

사용자 정의 효과의 경우, type은 해당 사용자 정의 효과에 대한 custfx 객체의 ID여야 합니다.

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

spawnFx와 동일하게 작동하지만, 단일 좌표 대신 두 개의 좌표를 전달합니다. 형식은 다음과 같습니다: {x: 100, y: 100}. 예를 들어: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"); 해당 효과를 지원하는 경우(클라이언트 측에서 제어가 가능한 것과 동일), 이 효과는 두 지점 사이를 "이동"합니다.

다음 효과 유형은 항상 spawnFx 대신 spawnFxBetweenPoints를 사용해야 합니다:빔 색상,숨결 색상,튀김 색상

spawnFxWithDefinition(x, y, 정의JSON, 페이지ID)

지정된 위치 x,y에서 효과 정의를 위한 JSON을 사용하여 임시 사용자 정의 효과를 생성합니다. 페이지id를 생략하거나 'undefined'를 전달하면, 플레이어가 현재 위치한 페이지(캠페인 객체의 'playerpageid')가 기본값으로 사용됩니다.

definitionJSON은 정의용 JSON 사양을 따르는 자바스크립트 객체입니다. Custom FX.

주크박스 재생 목록

playJukeboxPlaylist(playlistid)

재생 기능은 재생 목록의 폴더 ID(캠페인 객체의 "_jukeboxfolder" 속성에서 가져옴)를 입력으로 받아, 게임 내 모든 플레이어에게 해당 재생 목록의 재생을 시작합니다.

stopJukeboxPlaylist()

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

기타

sendPing(왼쪽, 위쪽, 페이지ID, (선택적) 플레이어ID, (선택적) 이동모두, (선택적) 표시대상)

테이블탑에 "핑"을 보냅니다(플레이어가 마우스 버튼을 누르고 있는 것과 동일합니다). 상단/좌측 좌표를 지정해야 하며, 핑을 보낼 페이지의 페이지 ID를 명시해야 합니다. 선택적으로 핑을 수행한 플레이어의 ID를 지정할 수 있습니다. 지정하지 않으면 "api"로 간주되며 핑은 노란색으로 표시됩니다.

플레이어의 시점도 해당 위치로 이동시키려면 moveAll 옵션에 "true"를 전달할 수 있습니다.

플레이어가 핑을 보거나 핑에 의해 이동될 수 있도록 visibleTo에 플레이어 ID를 설정할 수 있습니다. 이는 단일 플레이어 ID, 배열 또는 쉼표로 구분된 문자열로 제시됩니다.

on("채팅:message", function(msg) {
  // 테스트 실행을 위해 채팅창에 "!pingtest" 입력
  if(msg.type == "api" && msg.content.indexOf("!pingtest") !== -1) {
 
    // 특정 플레이어 조회 시 findObjs({_type: "player"})[i].id 대신 null을 3번째 매개변수로 사용하세요.
    players = findObjs({_type: "player"});
    player1 = players[1].id;
    player2 = players[2].id;
 
    // 모든 플레이어의 ID를 배열로 생성
    var allPlayerIDs = players.map(function(player) {
      return player['id'];
    });
 
    // 이 페이지의 모든 플레이어에게 동일한 위치로 핑을 보냅니다.
    sendPing(300, 300, Campaign().get('playerpageid'), null, true);
    setTimeout(function() {
        // 이 페이지의 모든 플레이어에게 동일한 위치로 핑 전송
        sendPing(1500, 500, Campaign().get('playerpageid'), msg.playerid, true, "");
    }, 1000);
    setTimeout(function() {
        // 지정된 플레이어만 이 위치로 핑 전송
        sendPing(1200, 500, Campaign().get('playerpageid'), null, true, player1);
    }, 2000);
    setTimeout(function() {
        // 플레이어 ID 배열(플레이어 1과 2)을 이 위치로 핑 전송
        sendPing(900, 100, Campaign().get('playerpageid'), player2, true, [player1, player2]);
    }, 3000);
    setTimeout(function() {
        // 쉼표로 구분된 목록을 문자열로 이 위치에 전송
        sendPing(300, 300, Campaign().get('playerpageid'), player1, true, allPlayerIDs.join());
    }, 4000);
 
  }
})

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

Roll20에서 "유닛"은 화면상 항상 70픽셀입니다. "단위"는 거리와 격자가 구축되는 기초 요소입니다. 기본적으로:

1 단위 = 5 피트
1 단위 = 1 격자 사각형
따라서, 5 ft = 1 단위 = 1 제곱

그러나 GM은 격자의 크기와 거리 척도 모두를 변경할 수 있습니다. 1 유닛은 항상 70픽셀이지만, GM은 설정을 변경하여 1 유닛을 10피트(즉, 70픽셀 = 10피트)로 하거나, 각 격자 공간을 2 유닛(즉, 각 격자 공간이 140픽셀이 됨)으로 할 수 있습니다.