모드 스크립트: 이벤트

2026년 09월 28일 14:51

on(event, callback)을 사용하여 처리할 수 있는 이벤트에는 여러 가지 유형이 있습니다. 이벤트 유형은 ‘준비’, ‘변경’, ‘추가’, ‘삭제’, ‘채팅’의 다섯 가지가 있습니다. 'ready'를 제외하고, 이름에는 객체 유형(또는 채팅의 경우 메시지 )이 포함되며, 'change'에는 속성이 포함될 수 있습니다. 변경되는 각 객체마다 해당 이벤트가 한 번씩 발생합니다. 객체의 여러 속성이 동시에 변경되는 경우, 단 하나의 “전역” 이벤트(예: change:graphic)만 트리거되며, 여기에 사용자가 바인딩한 속성별 이벤트가 추가로 발생합니다.

콜백 매개변수

이벤트를 수신하면, 해당 이벤트가 발생할 때마다 실행되는 ‘콜백’이라는 함수를 생성하게 됩니다. 콜백 함수는 무엇이 변경되었는지 알려주는 매개변수를 받아, 이에 따라 어떻게 처리할지 결정할 수 있게 해줍니다.

행사	인수
`준비됨`	없음
`변경`	`obj` (변경 후의 Roll20 객체), `prev` (이전 속성을 가진 일반 객체)
`캐릭터`	`obj` (새로운 객체)
`파괴하다`	`obj` (제거된 오브젝트; 캠페인 내에 여전히 존재한다고 가정하지 마십시오)
`채팅`	`msg` — ‘모드 스크립트: 채팅’ 참조

obj

변경된 객체. 이 객체에 가하는 모든 변경 사항은 게임에도 저장됩니다. 따라서 그래픽 객체를 왼쪽으로 이동시키려면, set을 사용하여 obj의 left 속성을 수정하면 됩니다.

obj.get("property") 는 해당 속성의 현재 값을 반환합니다.
obj.set("property", "newvalue") 는 해당 속성에 새로운 값을 설정합니다. 여러 속성을 한 번에 변경하려는 경우 객체를 전달할 수 있습니다: obj.set({left: 10, top: 20}).

이는 이 이벤트로 인해 변경이 이루어지기 전의 obj 객체의 속성을 나타내는 객체입니다. 부동산의 가치가 “얼마나” 변동했는지 파악하는 데 유용합니다.

참고: prev는 Roll20 객체가 아닙니다. 대괄호 표기법이나 점 표기법을 사용하여 속성에 접근합니다: prev["bar1_value"] 또는 prev._id. 이 키에 대해 get/set 메서드를 호출할 수 없으며, 읽기 전용 키의 경우 밑줄을 생략할 수 없습니다(prev.id는 prev._id가 아닙니다).

캐릭터 및 핸드아웃과 관련하여, 이전 게시물의 ‘blob’ 필드인 ‘bio’, ‘notes’, ‘gmnotes’는 텍스트가 아닌 내부 식별자입니다. _defaulttoken 캐릭터도 블롭입니다. 'graphic gmnotes'는 일반 문자열입니다. 필요한 경우 이전 BLOB 값을 직접 캐시에 저장해 두세요.

이벤트 순서 지정

이벤트는 첫 번째로 바인딩된 것부터 마지막 바인딩된 순서대로, 또한 특정 속성에서 일반 객체 순으로 동기적으로(각 함수는 이전 함수가 완료될 때까지 시작되지 않음) 발생합니다. 따라서 다음과 같은 경우:

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

객체의 left 속성이 변경된 경우, 순서는 function3, function1, function2 순이 됩니다.

캠페인에 여러 스크립트가 있는 경우, 해당 스크립트는 ‘Mod 스크립트’ 설정 페이지에 표시된 순서대로, 왼쪽에서 오른쪽으로 순차적으로 로드됩니다.

참고: 스크립트의 set() 메서드는 해당 속성에 대한 변경 이벤트를 발생시키지 않습니다. 플레이어가 토큰을 이동하면 change:graphic이 표시됩니다. 스크립트가 set()을 사용하여 left 값을 변경하더라도, 해당 변경으로 인해 change:graphic 이벤트가 발생하지 않습니다. 스크립트를 통해 그래픽을 생성하면 change:graphic이 실행됩니다. sendChat()은 !로 시작하는 메시지를 포함하여 채팅:message를 실행합니다.. Virtual status_* 속성은 자체 이벤트를 발생시키지 않으므로, change:graphic:statusmarkers 이벤트를 수신해야 합니다.

준비됨

이 이벤트는 샌드박스가 시작될 때마다, 캠페인 데이터가 로드된 후 한 번씩 발생합니다. 이미 존재하는 객체는 준비가 완료된 후에야 조회하십시오. ready 이벤트가 발생하기 전에 추가 이벤트(예: add:graphic)를 바인딩하면, 캠페인에 이미 존재하던 오브젝트에 대한 추가 이벤트도 수신하게 됩니다. 스크립트는 Mod Scripts 설정의 순서대로 왼쪽에서 오른쪽으로 로드되며, ready 핸들러는 바인딩된 순서대로 실행됩니다.

콜백 매개변수: 없음

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

채팅 이벤트

`채팅:메시지`

sendChat()을 통해 전송된 메시지를 포함하여, 새로운 채팅 메시지가 수신될 때마다 트리거됩니다. 콜백은 msg 객체를 전달받습니다. 메시지 유형에는 일반, 주사위 결과, GM 주사위 결과, 비밀 주사위 결과 (/sr), 초비밀 주사위 결과 (/ssr), 이모티콘, 귓속말, 설명, 다이렉트, API 등이 있습니다. !로 시작하는 메시지 type === "api" 이며 채팅에 표시되지 않습니다.

콜백 매개변수: msg

msg 속성의 전체 목록과 주사위 결과 처리에 대해서는 ‘Mod Scripts: 채팅’을 참조하십시오.

캠페인 행사

캠페인 객체는 모든 캠페인 속성에 대해 change:campaign 및 change:campaign:PROPERTY를 지원합니다. 다음은 대부분의 스크립트가 감지하는 항목들입니다:

`change:campaign:playerpageid`

플레이어가 현재 위치한 페이지가 변경될 때마다 발동됩니다.

`변경:캠페인:턴순서`

캠페인의 턴 순서 목록이 변경될 때마다 발동됩니다.

`변경:캠페인:이니셔티브페이지`

턴 순서가 페이지에 대해 숨겨지거나 표시될 때마다 발동됩니다. 이는 현재 활성화된 페이지의 ID와 동일하지 않을 수 있습니다. 이 값이 false로 설정된 경우(모드 스크립트에 의해 false로 설정된 경우 포함), 모든 GM 및 플레이어의 턴 순서가 종료됩니다. 유효한 페이지 ID로 설정하면 모든 GM/플레이어에게 열립니다.

객체 이벤트

각 객체 유형은 다음을 지원합니다:

add:TYPE
변경:TYPE
변경:유형:속성
파기:유형

또한 특정 객체 ID에 바인딩할 수도 있습니다: change:TYPE:ID, change:TYPE:ID:PROPERTY, destroy:TYPE:ID.

각 유형의 속성에 대해서는 ‘모드 스크립트: 객체’를 참조하십시오.

`change:graphic`

그래픽 오브젝트(토큰, 맵, 카드 등 테이블탑 위의 거의 모든 오브젝트)가 변경될 때마다 발동됩니다.

참고: 스크립트를 통해 생성된 그래픽 객체는 생성 시 이 이벤트를 트리거합니다.

콜백 매개변수: obj, prev

on("change:graphic", function(obj, prev) {
  //여기서 "obj"를 사용하여 작업을 수행합니다. "prev"는 이전 값들의 목록입니다.
  // "obj"와 "prev"는 서로 다른 유형의 객체임을 유의하십시오.
  // obj를 사용하려면 obj.get("name");을 사용해야 합니다.
  // prev를 사용하려면 prev["name"];을 사용할 수 있습니다.
});

`change:graphic:(속성)`

객체의 각 특정 속성에 대해 이벤트를 바인딩할 수도 있습니다. 따라서 로테이션 이 변경될 때만 실행하고 싶은 스크립트가 있다면 다음과 같이 하면 됩니다:

on("change:graphic:rotation", function(obj, prev) {
  //회전 각도를 항상 0으로 재설정하여, 아무도 객체를 회전할 수 없도록 합니다.
  obj.set("rotation", 0);
});

`add:graphic`

그래픽 객체가 테이블탑에 처음 추가될 때마다 트리거됩니다. ‘ready’ 이벤트 외부에서 이 이벤트에 바인딩한 경우, 테이블탑이 시작될 때 기존 객체에 대해서도 이 이벤트가 호출됩니다.

콜백 매개변수: obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // ready 이후 추가된 그래픽만 처리합니다.
});
on("ready", function() {
  started = true;
});

`파괴:그래픽`

그래픽 객체가 테이블탑 위에서 제거될 때마다 트리거됩니다.

콜백 매개변수: obj

그래픽 하위 유형

그래픽도 _subtype을 사용하여 이벤트를 발생시킵니다. 맵은 토큰 하위 유형을 사용합니다.

하위 유형	행사	메모
`토큰`	`add:token` `변경:토큰` `변경:토큰:PROPERTY` `삭제:토큰`	토큰과 맵 그래픽.
`카드`	`add:card` `변경:카드` `변경:카드:속성` `삭제:카드`	테이블탑 위에 놓인 카드(그래픽). 아래 참고 사항을 확인해 주세요.
`dicetoken`	`add:dicetoken` `변경:dicetoken` `변경:dicetoken:PROPERTY` `삭제:dicetoken`	테이블탑에 놓인 주사위 토큰들.

'card'는 Roll20 객체 유형이자 그래픽 하위 유형이므로, change:card 및 이와 유사한 이벤트에 대한 핸들러는 올바른 유형의 객체에 대해 이벤트가 발생하고 있는지 확인하기 위해 객체 유형을 명확히 구분해야 합니다(예: obj.get("_type")).

모든 객체 유형

아래의 모든 유형은 add:TYPE, change:TYPE, change:TYPE:PROPERTY 및 destroy:TYPE을 지원합니다.

유형	이벤트 예시	메모
`능력`	`add:능력` `변경:능력` `파괴:능력`
`특성치`	`add:속성` `변경:속성` `삭제:속성`
`캠페인`	`변경:캠페인` `변화:캠페인:플레이어페이지ID`	캠페인 객체는 단 하나뿐입니다. 스크립트는 일반적으로`객체의 추가나 삭제보다는` `변경` 사항을 감지합니다.
`카드`	`add:card` `변경:카드` `삭제:카드`	덱 카드 객체. 또한 그래픽 하위 유형 — `_type을` 기준으로 구분하십시오.
`캐릭터`	`추가:캐릭터` `변경:캐릭터` `삭제:캐릭터`
`custfx`	`add:custfx` `변경:custfx` `삭제:custfx`	커스텀 FX.
`덱`	`add:deck` `변경:덱` `파기: 덱`
`문`	`추가:문` `변경:문` `파괴:문`	최신 VTT 엔진.
`그래픽`	`add:graphic` `변경:그래픽` `그래픽 삭제`	또한 하위 유형 이벤트(`토큰`, `카드`, `주사위 토큰`)도 발생시킵니다.
`손`	`추가:hand` `변경:hand` `삭제:hand`
`핸드아웃`	`add:핸드아웃` `변경:핸드아웃` `삭제:핸드아웃`
`주크박스 트랙`	`add:jukeboxtrack` `변경:jukeboxtrack` `삭제:jukeboxtrack`
`매크로`	`add:매크로` `변경:매크로` `삭제:매크로`
`페이지`	`추가:페이지` `변경:페이지` `삭제:페이지`	계층 구조가 변경되면 `change:페이지:_placement` 및 `change:페이지:_path` 이벤트도 발생합니다.
`pageFolder`	`add:pageFolder` `변경:pageFolder` `삭제:pageFolder`	Mod Script 샌드박스 v1.5 전용입니다.
`경로`	`add:path` `변경:경로` `삭제:경로`	전통적인 테이블탑 그림들.
`pathv2`	`add:pathv2` `변경:pathv2` `삭제:pathv2`	최신 VTT 엔진.
`핀`	`add:pin` `변경:핀` `파기:핀`	최신 VTT 엔진.
`플레이어`	`add:player` `change:player` `플레이어 삭제`
`rollabletable`	`add:rollabletable` `변경:rollabletable` `삭제:rollabletable`
`tableitem`	`add:tableitem` `변경:테이블 항목` `삭제:테이블항목`
`문자 입력`	`add:text` `변경:text` `삭제:text`
`창문`	`add:window` `변경:창` `삭제:창`	최신 VTT 엔진.

Mod Script 샌드박스 v1.5 전용입니다. pageFolder 객체에는 add:pageFolder, change:pageFolder, destroy:pageFolder 이벤트와 change:pageFolder:name과 같은 속성 이벤트가 있습니다. 또한 페이지 메뉴 계층 구조가 변경되면 페이지에서는 change:page:_placement 및 change:page:_path 이벤트도 발생시킵니다.

점프게이트 / 최신 VTT 엔진 객체 유형(pathv2, pin, window, door)은 VTT 엔진의 기능이며, 샌드박스 버전의 기능이 아닙니다. 최신 VTT 엔진을 기반으로 한 v1.0 게임에도 여전히 이러한 오브젝트 유형과 해당 이벤트들이 포함되어 있습니다.