모드 스크립트: 함수 설명서

2026년 09월 28일 14:51

Roll20은 핵심 자바스크립트나 다른 라이브러리에 포함되지 않은 여러 가지 기능을 제공합니다.

게임에서는 Mod Script 샌드박스 v1.0 (Campaign().sandboxVersion === "1.0") 또는 v1.5 ("1.5")가 실행될 수 있습니다. ‘Mod Script 샌드박스 v1.5’로 표시된 기능만 해당됩니다. v1.0에서는 작동하지 않습니다.

전역 변수

변수	설명
`_`	이것은 Underscore.js 라이브러리의 네임스페이스 객체입니다.
`state`	상태 객체의 속성은 게임 세션 간에 유지됩니다.

_ (밑줄)

이것은 Underscore.js 라이브러리의 네임스페이스 객체입니다. 언더스코어는 컬렉션 조작을 위한 다양한 함수를 제공합니다.

state

상태 객체의 속성은 게임 세션 간에 유지됩니다. 또한 캠페인 내의 모든 Mod 스크립트 간에 동일한 상태 객체가 공유되므로, 상태에 값을 기록할 때는 이름 충돌을 피하기 위해 차지하는 공간을 최대한 줄이는 것이 강력히 권장됩니다. 참고: 상태는 JSON으로 직렬화되므로 함수나 순환 참조가 있는 객체를 저장할 수 없습니다.

글로벌 함수

반환 유형	함수	설명
`Roll20 객체`	`캠페인`	싱글톤 Campaign Roll20 객체를 가져옵니다.
`Roll20 객체`	`객체 생성`	새로운 Roll20 객체를 생성합니다.
`Roll20 객체 배열`	`필터 객체`	예측자 테스트를 통과하는 모든 Roll20 객체를 가져옵니다.
`Roll20 객체 배열`	`findObjs`	지정된 속성 집합과 일치하는 속성을 가진 모든 Roll20 객체를 가져옵니다.
`Roll20 객체 배열`	`getAllObjs`	캠페인 내 모든 Roll20 객체를 가져옵니다.
`다르다`	`getAttrByName`	Roll20 객체의 속성에 대한 현재 값 또는 최대 값을 가져옵니다.
`다르다`	`getComputed`	Mod Script 샌드박스 v1.5 전용입니다. Beacon 계산 속성을 가져옵니다.
`다르다`	`getSheetDefaultValue`	특정 속성 이름에 대한 기본 캐릭터 시트 정보를 가져옵니다.
`다르다`	`getSheetItem`	시트 항목(속성; v1.5에서는 Beacon / `user.*`도 포함)을 가져옵니다.
`Roll20 객체`	`getObj`	특정 Roll20 객체를 가져옵니다.
	`로그`	Mod 출력 콘솔에 메시지를 기록합니다.
	`지금 접속하세요!`	이벤트 핸들러를 등록합니다.
	`onSheetWorkerCompleted`	시트 제작자 스크립트의 전체 스택이 완료된 후 실행될 일회성 이벤트 핸들러를 등록합니다.
	`performAction`	Mod Script 샌드박스 v1.5 전용입니다. 비콘 시트 작업을 수행합니다.
`부울`	`플레이어가 GM입니다`	플레이어가 현재 GM 권한을 보유하고 있는지 확인합니다.
	`playJukeboxPlaylist`	주크박스 재생 목록을 재생하기 시작하세요.
`숫자`	`난수`	무작위 정수 값을 생성합니다.
	`sendChat`	채팅 메시지를 보냅니다.
	`sendPing`	마우스 왼쪽 버튼을 누르고 있는 것과 유사한 핑을 보냅니다.
	`setAttrs`	캐릭터에 하나 이상의 속성을 설정합니다.
	`setComputed`	Mod Script 샌드박스 v1.5 전용입니다. 쓰기 가능한 Beacon 계산 속성을 설정합니다.
	`setSheetItem`	시트 항목(속성; v1.5에서는 Beacon / `user.*`도 포함)을 설정합니다.
	`스폰 효과`	파티클 이미터를 생성합니다.
	`점 사이에서 효과 생성`	한 지점에서 다른 지점으로 이동하는 파티클 이미터를 생성합니다.
	`정의된 효과 생성`	FX Roll20 객체로 표현되지 않는 파티클 이미터를 생성합니다.
	`stopJukeboxPlaylist`	현재 재생 중인 모든 주크박스 재생 목록을 중지합니다.
	`toAbove`	Mod Script 샌드박스 v1.5 전용입니다. 동일한 레이어에 있는 한 개체를 다른 개체의 바로 위에 배치합니다.
	`뒤로`	그래픽, 텍스트, 경로 또는 pathv2를 해당 레이어에 있는 다른 개체들 아래로 이동합니다.
	`아래로`	Mod Script 샌드박스 v1.5 전용입니다. 동일한 레이어에서 한 개체를 다른 개체의 바로 아래에 배치합니다.
	`toFront`	그래픽, 텍스트, 경로 또는 pathv2를 해당 레이어의 다른 개체들 위로 이동합니다. ID가 아니라 객체를 전달하세요.
	`카드 도우미`	`shuffleDeck`, `cardInfo`, `recallCards`, `dealCardsToTurn`, `drawCard`, `pickUpCard`, `takeCardFromPlayer`, `playCardToTable`, `giveCardToPlayer` — ‘객체: 덱’ 항목 참조.

캠페인

매개변수

매개변수 없음

반품

Roll20 싱글턴 캠페인 객체.

예시

var currentPageID = Campaign().get('playerpageid'),
  currentPage = getObj('페이지', currentPageID);

Campaign().sandboxVersion은 "1.0" 또는 "1.5"입니다. Campaign().nodeVersion은 Node.js 버전 문자열입니다. Mod Script 샌드박스 v1.5 전용입니다. sheetName, computedSummary 및 actionSummary. ‘개체: 캠페인’을 참조하십시오.

`객체 생성`

매개변수

TYPE (문자열) 생성할 Roll20 객체의 유형입니다. 'graphic', 'text', 'path', 'pathv2', 'character', '능력', '속성', '핸드아웃', 'rollabletable', 'tableitem', '매크로', 'card', 'deck', 'custfx', 'window', 'door' 및 'pin'을 생성할 수 있습니다 . Mod Script 샌드박스 v1.5 전용입니다. 'pageFolder'.

속성 (객체) Roll20 객체의 속성에 적용할 초기값입니다.

반품

생성된 Roll20 객체.

예시

상위 객체가 있는 Roll20 객체를 생성할 때(예: 캐릭터 Roll20 객체의 자식인 속성 Roll20 객체를 생성하는 경우), 속성 항목에 상위 객체의 ID를 반드시 지정해야 합니다.

on('ready', function() {
  on('add:character', function(obj) {
    createObj('속성', {
      name: 'Strength',
      current: 0,
      max: 30,
      characterid: obj.id
    });
  });
});

경로를 생성할 때는 경로 ( _path로 저장됨)와 pageid를 지정하십시오. 밑줄이 없는 경로는 생성 당시의 이름입니다. 그 후에는 읽기 전용으로 설정됩니다.

createObj('path', {
  pageid: Campaign().get('playerpageid'),
  left: 7000,
  top: 140,
  width: 140,
  height: 140,
  레이어: 'objects',
  path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Roll20에서 핸드아웃 개체를 생성할 때는 생성 시점에 텍스트나 GM 노트를 설정할 수 없습니다.

var handout = createObj('handout', {
  name: '당신에게 보내는 편지',
  inplayerjournals: 'all',
  archived: false
});
handout.set('notes', '노트는 핸드아웃이 생성된 후에만 설정할 수 있습니다.');
handout.set('gmnotes', 'gmnotes는 notes와 별도의 호출로 설정해야 합니다.');

필터 객체

매개변수

CALLBACK (함수) 모든 Roll20 객체를 검사하는 데 사용되는 술어 함수입니다. 콜백 함수는 Roll20 객체를 매개변수로 받아, true(filterObjs 반환 값에 포함될 Roll20 객체의 경우) 또는 false(그 외 모든 Roll20 객체의 경우)를 반환해야 합니다.

반품

예측자 테스트를 통과한 Roll20 객체들의 배열.

findObjs

매개변수

속성 (Object) 캠페인 내 Roll20 객체와 매칭되는 키-값 쌍의 모음입니다.

OPTIONS (객체, 선택 사항)

caseInsensitive — true인 경우, 문자열 비교 시 대소문자를 구분하지 않습니다.
startsWith — true인 경우, 문자열 값이 접두사로 일치합니다.
tagMatch — 태그 일치 시: 'all' (기본값; 객체에 나열된 모든 태그가 있음), 'any' (적어도 하나), 'only' (나열된 집합과 정확히 일치).

반품

속성이 속성값과 일치하는 Roll20 객체들의 배열입니다. 키에서 앞쪽의 밑줄을 생략할 수 있습니다. 즉, ‘type ’과 ‘_type ’ 모두 일치합니다.

예시

var npcs = findObjs({ type: '캐릭터', controlledby: '' });
var knights = findObjs({ type: '캐릭터', name: 'Sir' }, { startsWith: true });

getAllObjs

매개변수

매개변수 없음

반품

캠페인 내 모든 Roll20 객체의 배열.

getAttrByName

매개변수

CHARACTER_ID (문자열) 캐릭터의 ID입니다. ATTRIBUTE_NAME (문자열) 속성의 이름입니다. VALUE_TYPE (문자열, 선택 사항) “current” 또는 “max” (기본값은 “current”입니다).

반품

current 또는 max 속성. 설정되지 않은 경우, 캐릭터 시트의 기본값이 사용됩니다(있는 경우).

getComputed

Mod Script 샌드박스 v1.5 전용입니다. (v1.0에서는 이 이름이 아무 작업도 수행하지 않는 스텁입니다.)

매개변수

객체: { characterId, property, args?, playerId? }.

Beacon 캐릭터 시트를 사용할 때, 계산된 속성의 값을 가져옵니다. Campaign().computedSummary를 사용하여 이름 목록을 표시합니다. playerId는 선택 사항이지만, 일부 Beacon 기능(예: 롤 쿼리)에서는 이 값이 필요합니다.

getSheetDefaultValue

매개변수

ATTRIBUTE_NAME (문자열), VALUE_TYPE (문자열, 선택 사항) “current” 또는 “max”.

반품

해당 필드의 실제 문자 값이 아니라 시트의 기본값입니다.

getSheetItem

매개변수

getSheetItem(characterId, property, valtype?, options?) — 비동기 (Promise).

v1.0에서는 이 함수가 getAttrByName을 감싸고 있습니다. Mod Script 샌드박스 v1.5 전용입니다. Beacon 시트에서는 user.*라는 이름의 계산된 속성과 사용자 정의 속성도 읽어옵니다.

getObj

매개변수

TYPE (문자열), ID (문자열)

반품

지정된 Roll20 객체.

on('채팅:message', function(msg) {
  var sendingPlayer = getObj('player', msg.playerid);
});

로그

매개변수

메시지(변동 가능)가 모드 출력 콘솔에 표시됩니다. JSON.stringify를 사용하여 변환되었습니다.

Mod Script 샌드박스 v1.5 전용입니다. 오류 메시지에는 종종 [Roll20 캐릭터 -id]와 같은 컨텍스트 객체가 포함됩니다.

지금 접속하세요!

매개변수

EVENT (문자열) 이벤트에는 ready, change, add, destroy, 채팅의 다섯 가지 유형이 있습니다. 'ready'를 제외하고, 이벤트에 객체 유형을 매칭하십시오. 채팅의 경우 해당 유형은 항상 ‘메시지’입니다. 변경 이벤트는 속성, 객체 ID 또는 둘 모두를 지정할 수도 있습니다: change:graphic:left, change:graphic:ID, change:graphic:ID:left. 그래픽은 또한 change:token 및 change:dicetoken과 같은 하위 유형 이벤트도 발생시킵니다. ‘행사’를 참조하십시오.

CALLBACK(함수)의 ready 이벤트에는 콜백 매개변수가 없습니다. 변경 이벤트에는 obj 매개변수(변경 후의 Roll20 객체)와 prev 매개변수(변경 전의 속성을 가진 일반 JavaScript 객체)가 있습니다. add 이벤트에는 obj 매개변수(새 객체)가 있습니다. destroy 이벤트에는 obj 매개변수(더 이상 존재하지 않는 객체)가 있습니다. 채팅 이벤트에는 msg 매개변수(메시지의 세부 정보)가 있습니다.

반품

(공백)

이벤트는 등록된 순서대로 발생하며, 가장 구체적인 이벤트부터 가장 덜 구체적인 이벤트 순으로 발생합니다. 이 예제에서 Roll20 그래픽 객체의 left 속성이 변경되면 function3이 호출되고, 그 다음 function1이 호출된 뒤 function2가 호출됩니다.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

새로운 세션이 시작될 때, 이미 캠페인에 존재하는 Roll20 객체에 대해 ‘이벤트 추가’가 실행되도록 시도합니다. 이러한 현상을 방지하려면, ` ready ` 이벤트가 발생될 때까지 ` add ` 이벤트 등록을 미루면 됩니다.

on('add:graphic', function(obj) {
  // 세션이 시작되면, 캠페인 내의 모든 그래픽에 대해 이 함수가 호출됩니다.
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // 이 함수는 새로운 Roll20 그래픽 객체가 생성될 때 *오직 그때만* 호출됩니다.
  });
});

변경 이벤트의 ‘prev’ 매개변수는 Roll20 객체가 아닙니다. get이나 set을 사용할 수 없으며, 읽기 전용 속성의 경우 앞쪽에 오는 밑줄을 생략할 수 없습니다. prev.id 대신 prev._id를 사용하세요.

캐릭터 및 핸드아웃 블롭 필드(bio, notes, gmnotes)와 캐릭터의 _defaulttoken의 경우, prev는 텍스트가 아닙니다. 'graphic gmnotes'는 일반 문자열입니다. 필요한 경우 이전 BLOB 값을 직접 캐시에 저장해 두세요.

onSheetWorkerCompleted

매개변수

CALLBACK (함수) 현재 스택에 있는 시트 제작자 스크립트의 처리가 완료되면 호출됩니다. setWithWorker 호출 전에 호출되도록 의도되었습니다. 한 번만 실행됩니다. 콜백은 { workersExecuted: boolean }을 수신할 수 있습니다.

performAction

Mod Script 샌드박스 v1.5 전용입니다. (v1.0에서는 이 이름이 아무 작업도 수행하지 않는 스텁입니다.)

매개변수

{ characterId, action, args?, playerId? }

비콘 시트 작업을 수행합니다. Campaign().actionSummary를 사용하여 목록 이름을 나열합니다. playerId는 선택 사항이지만, 일부 Beacon 기능에서는 이 값이 필요합니다. 이름이 비콘 액션이 아닌 경우, v1.5는 sendChat을 통해 해당 이름의 캐릭터 능력이 될 수 있습니다.

플레이어가 GM입니다

매개변수

PLAYER_ID (문자열)

반품

플레이어가 현재 GM 권한을 가지고 있는 경우 true입니다.

특히 모드 스크립트 명령어를 GM만 사용할 수 있도록 제한하는 데 유용합니다. msg.type !== 'api'는 그대로 두세요. — 이것이 명령 메시지 유형입니다.

playJukeboxPlaylist

매개변수

PLAYLIST_ID (문자열) 재생을 시작할 재생 목록의 ID입니다.

난수

매개변수

MAX (숫자) 포함 최대값.

반품

1과 max 사이의 임의의 정수. 주사위 같은 범위를 설정할 때는 Math.random() 보다 이 방법을 사용하는 것이 좋습니다.

sendChat 비동기

매개변수

SPEAKINGAS (문자열) 이름, 또는 플레이어|플레이어_ID / 캐릭터|캐릭터_ID. MESSAGE (문자열). CALLBACK (함수, 선택 사항) — 결과가 채팅에 표시되지 않고 콜백 함수로 전달됩니다. OPTIONS (Object, 선택 사항) noarchive, use3d.

명령 버튼을 보려면 ‘Mod Scripts: 채팅’을 참조하세요 ([label](!command)).

sendPing

매개변수

LEFT, TOP, PAGE_ID, PLAYER_ID (선택 사항), MOVEALL (선택 사항), VISIBLETO (선택 사항). player_id를 생략하면 핑 색상은 노란색입니다. moveAll이 true인 경우, 뷰가 핑을 중심으로 정렬됩니다. visibleTo는 플레이어 ID, ID 배열 또는 쉼표로 구분된 문자열일 수 있습니다.

setAttrs

매개변수

CHARACTER_ID (문자열), ATTRIBUTE_OBJ (이름 → 값 형식의 객체). _max 로 끝나는 이름은 최대값을 설정합니다. 반복되는 $n 이름을 반복하는 기능이 지원됩니다. options.silent는 setWithWorker 대신 set을 사용합니다.

setComputed

Mod Script 샌드박스 v1.5 전용입니다.

{ characterId, property, args?, playerId? } — 쓰기 가능한 Beacon 계산 속성을 설정합니다. Campaign().computedSummary를 참조하십시오.

setSheetItem

setSheetItem(characterId, property, value, valtype?, options?) — 비동기. v1.0에서는 속성을 설정합니다. Mod Script 샌드박스 v1.5 전용입니다. 또한 Beacon 계산 속성과 user.* 사용자 정의 속성도 포함됩니다. 사용 가능한 옵션으로는 createAttr, withWorker, allowThrow 등이 있습니다.

스폰 효과

매개변수

LEFT (숫자) 파티클 이미터를 배치할 x좌표. TOP (숫자) y좌표. TYPE (문자열) 내장 효과의 경우, “type-color” 형식이며, 여기서 type은 bomb, bubbling, burn, burst, explode, glow, missile, nova 중 하나이고, color는 acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, water 중 하나입니다. 사용자 정의 효과의 경우, custfx 객체의 ID입니다. 참고: beam, breath, splatter는 spawnFx와 함께 사용할 수 없습니다. 자세한 내용은 spawnFxBetweenPoints를 참조하십시오. PAGE_ID (문자열, 선택 사항)의 기본값은 Campaign().get('playerpageid')입니다.

spawnFx(1400, 1400, '거품이 일고 있는 산');

점 사이에서 효과 생성

매개변수

START (객체) { x, y }. END (객체) { x, y }. TYPE(String)을 spawnFx로 설정하고, beam, breath, splatter를 추가합니다. PAGE_ID (문자열, 선택 사항).

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

Mod Script 샌드박스 v1.5 전용입니다. 빔형 효과가 종점을 정확히 가리킵니다(각도 계산 오류가 수정되었습니다).

정의된 효과 생성

매개변수

LEFT, TOP, DEFINITION (방출기를 설명하는 객체), PAGE_ID (선택 사항). 속성 이름에 대해서는 “객체에 적용되는 사용자 정의 FX” 문서를 참조하십시오.

spawnFxWithDefinition(1400, 1400, {
  maxParticles: 200,
  size: 15,
  sizeRandom: 3,
  lifeSpan: 20,
  lifeSpanRandom: 5,
  speed: 7,
  speedRandom: 2,
  gravity: { x: 0.01, y: 0.65 },
  angle: 270,
  angleRandom: 35,
  emissionRate: 1,
  startColour: [0, 35, 10, 1],
  startColourRandom: [0, 10, 10, 0.25],
  endColour: [0, 75, 30, 0],
  endColourRandom: [0, 20, 20, 0]
});

stopJukeboxPlaylist

현재 재생 중인 모든 주크박스 재생 목록의 재생을 중지합니다.

stopJukeboxPlaylist();

카드 도우미

두 샌드박스 버전 모두에서 이용 가능합니다. 자세한 내용은 ‘모드 스크립트: 오브젝트 (갑판)’에서 확인할 수 있습니다.

shuffleDeck(deckid, discard, newOrder)
cardInfo(설정)
recallCards(deckid, type)
dealCardsToTurn(deckid)
drawCard(deckid, cardid)
pickUpCard(cardid, fromDiscard)
takeCardFromPlayer(playerid, options)
playCardToTable(cardid, settings)
giveCardToPlayer(카드ID, 플레이어ID)

setDefaultTokenForCharacter

CHARACTER(캐릭터 객체), TOKEN(그래픽 객체). 둘 다 이미 존재해야 합니다. 토큰에서 캐릭터의 _defaulttoken 블롭을 기록합니다. 해당 필드를 설정하는 방법은 다음과 같습니다. set() 메서드는 그렇게 하지 않습니다.

toAbove

Mod Script 샌드박스 v1.5 전용입니다.

매개변수

OBJ (그래픽, 텍스트, 경로 또는 pathv2), TARGET (객체 또는 ID).

대상 바로 위에 같은 레이어에 obj를 배치합니다.

뒤로 / 앞으로

OBJ는 그래픽, 텍스트, 경로 또는 pathv2여야 합니다. ID가 아니라 객체를 전달하세요. v1.5에서는 이들의 처리 속도가 상당히 빨라졌으며, 해당 유형에는 toFront() / toBack() 인스턴스 메서드도 추가되었습니다.

아래로

Mod Script 샌드박스 v1.5 전용입니다.

대상 (객체 또는 ID) 바로 아래에 obj를 동일한 레이어에 배치합니다.