API: 함수 문서

2025년 11월 07일 18:31

전역 변수

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

_ (밑줄)

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

state

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

글로벌 함수

반환 유형	함수	설명
Roll20 객체	`캠페인`	싱글톤 Campaign Roll20 객체를 가져옵니다.
Roll20 객체	`객체 생성`	새로운 Roll20 객체를 생성합니다.
배열의 Roll20 객체	`필터 객체`	예측자 테스트를 통과하는 모든 Roll20 객체를 가져옵니다.
배열의 Roll20 객체	`findObjs`	지정된 속성 집합과 일치하는 속성을 가진 모든 Roll20 객체를 가져옵니다.
배열의 Roll20 객체	`getAllObjs`	캠페인 내 모든 Roll20 객체를 가져옵니다.
다양하다	`getAttrByName`	Roll20 객체의 속성에 대한 현재 값 또는 최대 값을 가져옵니다.
Roll20 객체	`getObj`	특정 Roll20 객체를 가져옵니다.
	`u`	메시지를 Mod(API) 콘솔에 기록합니다.
	`지금 접속하세요!`	이벤트 핸들러를 등록합니다.
	`onSheetWorkerCompleted`	전체 스택의 시트 작업자 스크립트 실행 후 실행될 일회성 이벤트 핸들러를 등록합니다. Sheet Worker Scripts 이 완료된 후 실행됩니다.
부울	`플레이어가 GM입니다`	플레이어가 현재 GM 권한을 보유하고 있는지 확인합니다.
	`playJukeboxPlaylist`	주크박스 재생 목록을 재생하기 시작하세요.
숫자	`난수`	무작위 정수 값을 생성합니다.
	`sendChat`	채팅 메시지를 보냅니다.
	`sendPing`	마우스 왼쪽 버튼을 누르고 있는 것과 유사한 핑을 보냅니다.
	`스폰 효과`	파티클 이미터를 생성합니다.
	`점 사이에서 효과 생성`	한 지점에서 다른 지점으로 이동하는 파티클 이미터를 생성합니다.
	`정의된 효과 생성`	FX Roll20 객체로 표현되지 않는 파티클 이미터를 생성합니다.
	`stopJukeboxPlaylist`	현재 재생 중인 모든 주크박스 재생 목록을 중지합니다.
	`뒤로`	그래픽 Roll20 객체를 동일한 테이블탑 레이어의 다른 모든 그래픽 아래로 이동합니다.
	`toFront`	그래픽 Roll20 객체를 동일한 테이블탑 레이어의 다른 모든 그래픽 위에 배치합니다.

캠페인

매개변수

매개변수 없음

반품

Roll20 싱글턴 캠페인 객체.

예시

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

객체 생성

매개변수

TYPE(String) 생성할 Roll20 객체의 유형. '그래픽', '텍스트', '경로', '캐릭터', '능력', '속성', '핸드아웃', '롤러블테이블', '테이블아이템', '매크로'만 생성할 수 있습니다. ATTRIBUTES(Object) Roll20 객체의 속성에 사용할 초기값입니다.

반품

생성된 Roll20 객체.

예시

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

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

Roll20 경로 객체를 생성할 때는 읽기 전용 속성인_path에 값을 반드시 지정해야 합니다. 이것은 Roll20 객체를 생성할 때 읽기 전용 속성의 값을 설정하지 못하도록 하는 규칙에 대한 예외입니다.

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    layer: 'objects',
    path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Roll20 오브젝트를 생성할 때, 생성 시점에 텍스트나 GM노트를 설정할 수 없습니다.

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
});
handout.set({
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'
});

필터 객체

매개변수

CALLBACK(함수) 모든 Roll20 객체를 테스트하기 위한 술어 함수. 콜백 함수는 Roll20 객체를 매개변수로 받으며, filterObjs 반환값에 포함될 Roll20 객체에 대해서는 true를, 그 외 모든 Roll20 객체에 대해서는 false를 반환해야 합니다.

반품

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

예시

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
});

findObjs

매개변수

속성(객체) 캠페인 내 Roll20 객체와 매칭할 키:값 쌍의 모음입니다. 옵션(객체, 선택적) options.caseInsensitive가 true인 경우 Roll20 객체와 속성 간의 문자열 비교는 대소문자를 구분하지 않습니다.

반품

속성이속성과 일치하는 Roll20 객체 배열.

예시

var npcs = findObjs({ type: 'character', controlledby: '' });

getAllObjs

매개변수

매개변수 없음

반품

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

예시

var 모든객체 = 모든객체들 가져오기();

getAttrByName

매개변수

CHARACTER_ID(문자열) 값을 조회하려는 속성 Roll20 객체의 상위 객체인 캐릭터 Roll20 객체의 ID입니다. ATTRIBUTE_NAME(String) 값을 조회하려는 속성 Roll20 객체의 이름.VALUE_TYPE(String, 선택적) "current" 또는 "max" 중 하나 (생략 시 기본값은 "current").

반품

해당 속성의전류또는최대속성. 원하는 속성이 설정되지 않은 경우, 캐릭터 시트에 지정된 기본값(기본값이 존재할 경우)이 대신 사용됩니다.

예시

var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

매개변수

TYPE(String) 가져올 Roll20 객체의 유형. ID(String) 가져올 Roll20 객체의 고유 ID.

반품

지정된 Roll20 객체.

예시

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

로그

매개변수

메시지(varies) Mod(API) 콘솔에 게시할 메시지. 메시지 매개변수는 JSON.stringify를 사용하여 문자열로 변환됩니다.

반품

(공백)

예시

on('chat:message', function(msg) {
    log('Message received from:');
    log(getObj('player', msg.playerid));
});

"메시지 발신자:"
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}

지금 접속하세요!

매개변수

이벤트(String) 이벤트에는 다섯 가지 유형이 있습니다: 준비됨 변경됨 추가됨 삭제됨 채팅 준비됨을 제외한 모든 이벤트 유형은 반드시 객체 유형과 함께 지정되어야 합니다. 채팅의 경우, 이는 항상 메시지입니다. 그 외 모든 것에 대해, 이는 Roll20 객체의 type 속성입니다. 객체 유형 외에도, 변경 이벤트는 선택적으로 지정된 Roll20 객체의 관찰할 속성을 명시할 수 있습니다. 이벤트의 2~3개 부분(유형, 객체, 선택적 속성)은 콜론(:)으로 구분됩니다. 따라서 유효한 이벤트 문자열에는 "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character", "destroy:handout" 등이 포함되나 이에 국한되지 않습니다. CALLBACK(함수) 지정된 이벤트가 발생할 때 호출될 함수입니다. 전달되는 매개변수는 이벤트 유형에 따라 다릅니다: - ready 이벤트는 콜백 매개변수가 없습니다. - change 이벤트는 obj 매개변수(변경 후 존재하는 Roll20 객체에 대한 참조)와 prev 매개변수(변경 이벤트 이전의 Roll20 객체와 속성이 일치하는 일반 JavaScript 객체)를 가집니다.add 이벤트에는 obj 매개변수가 있으며, 이는 새로 생성된 Roll20 객체를 참조합니다. destroy 이벤트에는 obj 매개변수가 있으며, 이는 더 이상 존재하지 않는 Roll20 객체를 참조합니다. chat 이벤트에는 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) {
    // 세션이 시작될 때, 캠페인 내 모든 그래픽에 대해 이 함수가 호출됩니다.
    // 새로운 그래픽 Roll20 객체가 생성될 때마다 이 함수도 호출됩니다.
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // 이 함수는 기존 그래픽이 아닌 새로 생성된 Roll20 그래픽 객체에 대해서만 호출됩니다
    });
});

변경이벤트의pre매개변수는 Roll20 객체가 아닌 일반적인 오래된 JavaScript 객체입니다. 따라서get또는set함수를 사용할 수 없으며, 읽기 전용 속성의 선행 언더스코어를 생략할 수 없습니다.

on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // 세 가지 모두 동등함
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // undefined
        id5 = prev.get('id'), // undefined is not a function
        id6 = prev._id;       // 올바른

    // 둘 다 동등함
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined is not a function
    prev.set({            // undefined is not a function
        left: 70
    });
    prev.left = 70;       // 올바름, 테이블탑에서는 아무것도 변경되지 않음
});

Roll20 객체(노트,GM 노트,바이오)의 비동기 필드인 캐릭터 및 핸드아웃의 경우,prev매개변수는 필요한 데이터를 포함하지 않습니다. (대신 시스템에서 사용하는 숫자 식별자가 부여될 것입니다.) 이러한 필드 중 하나의 이전 값에 접근해야 하는 경우, 해당 값을 직접 추적해야 합니다:

on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // do stuff...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    });
});

onSheetWorkerCompleted

매개변수

CALLBACK(함수) 시트 제작자 스크립트의 현재 '스택'이 완료될 때 호출될 함수입니다.

반품

(공백)

예시

이 함수는 setWithWorker 호출 전에 호출되도록 설계되었습니다. 콜백함수는 단 한 번만 호출됩니다.

var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // calculatedAttr.get('current')로 작업 수행;
});
mySourceAttr.setWithWorker({ current: 5 });

플레이어가 GM입니다

매개변수

PLAYER_ID(String) 확인 대상 플레이어 Roll20 객체의 ID입니다.

반품

플레이어가 현재 GM 권한을 가지고 있으면 true, 그렇지 않으면false입니다.

예시

이 기능은 특히 Mod(API) 명령어를 GM 전용으로 제한하는 데 유용합니다.

on('채팅:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    
);

playJukeboxPlaylist

매개변수

PLAYLIST_ID(String) 재생할 재생 목록의 ID입니다.

반품

(공백)

예시

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

난수

매개변수

MAX(Number) 반환할 최대 수치(포함).

반품

1(포함)과max(포함) 사이의 임의의 정수. 이 함수는Math.random()보다 더 나은 분포를 가지며, 이를 대신하여 권장됩니다. 이 함수는 양자 주사위 기능을 사용하지 않지만, 양자 주사위가 사용할 수 없는 경우 주사위 엔진이 대체로 사용하는 것과 동일한 의사 난수 알고리즘을 사용합니다.

예시

이 함수는 1부터최대값까지의 정수를 반환하므로, Roll20의 주사위 엔진 전체 기능을 필요로 하지 않을 때 빠르게 주사위 굴림 결과를 생성하는 데 이상적입니다. 주사위 엔진의 모든 기능을 필요로 하지 않는 경우의 모든 기능을 필요로 하지 않는 경우 주사위 굴림 결과를 빠르게 생성하는 데 이상적입니다.

var d20Result = randomInteger(20); // 대략 20면 주사위를 굴리는 것과 동일함

sendChat 비동기

매개변수

SPEAKINGAS(문자열) 전송 중인 메시지에 첨부할 이름. 말하기As가 player|player_id 또는 character|character_id 형식일 경우, 해당 플레이어 또는 캐릭터로 메시지가 전송됩니다. 그렇지 않으면 메시지는 GM이 /as 명령어를 사용한 것처럼 지정된 이름을 사용합니다. MESSAGE(String) 채팅에 전송할 메시지입니다. CALLBACK(Function, 선택적) 콜백이 지정된 경우, 채팅 메시지의 결과가 채팅에 표시되는 대신 해당 콜백 함수로 전달됩니다. 콜백 메서드의 매개변수는 메시지 객체 배열입니다. OPTIONS(Object, 선택적) options.noarchive가 true인 경우, 메시지는 채팅 기록에 추가되지 않습니다. options.use3d가 true인 경우, 메시지 내 주사위 굴림은 3D 주사위 기능을 사용합니다. 콜백이 지정된 경우 옵션은 적용되지 않습니다.

반품

(공백)

예시

sendChat('Example', '이것은 간단한 예시입니다.');

채팅:메시지이벤트를 트리거한 동일한 플레이어 또는 캐릭터로 메시지를 전송하는 코드를 쉽게 작성할 수 있습니다.

on('채팅:message', function(msg) {
    var 캐릭터 = findObjs({ type: 'character', name: msg.who })[0],
        player = getObj('player', msg.playerid),
        message = ' said something';

    if (character) sendChat('캐릭터|'+character.id, character.get('name')+message);
    else sendChat('플레이어|'+player.id, player.get('displayname')+message);
});

콜백매개변수는 Roll20의 주사위 엔진을 활용해야 할 때 유용합니다. 주사위 엔진을 활용해야 할 때 유용합니다. 콜백을 사용할 때speakingAs값은 특별히 필요하지 않습니다. 메시지가 채팅에 표시되지 않기 때문입니다.

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchive는주로 API 명령 버튼 채팅 기록을 막히지 않게 하기 위한 것입니다.

sendChat('시스템', '[변경 내용 지우기](!clear)\n[타일 추가](!add)\n[샘플 보기](!view)\n[레이아웃 저장](!save)', null, { noarchive: true });

sendPing

매개변수

LEFT(숫자) 핑을 배치할 x 좌표. TOP(숫자) 핑을 배치할 y 좌표. PAGE_ID(문자열) 핑을 배치할 Roll20 페이지 객체의 ID. PLAYER_ID(문자열, 선택적) 지정된 플레이어의 색상을 사용합니다. player_id가 생략되면 핑은 노란색으로 표시됩니다. MOVEALL(Boolean, 선택적) moveAll이 true인 경우, 해당 페이지의 모든 플레이어의 시야가 핑을 중심으로 정렬됩니다.

참고:현재는moveAll이true일 경우 GM만 뷰가 중앙 정렬됩니다. 이 동작은 문서화되어 있습니다 여기

반품

(공백)

예시

on('채팅:message', function(msg) {
    var obj;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id);
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // 선택된 토큰 중심으로 모든 플레이어 위치 조정
    }
});

스폰 효과

매개변수

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 중 하나여야 합니다. 사용자 정의 효과의 경우, 이는 FX Roll20 객체의 ID여야 합니다. 참고: 빔, 호흡, 그리고 튀김 유형은 spawnFx와 함께 사용할 수 없습니다. 대신 spawnFxBetweenPoints를 참조하십시오. PAGE_ID(String, 선택적) 입자 방출기를 배치할 Roll20 페이지 객체의 ID입니다. 생략된 경우 대신 Campaign().get('playerpageid')가 사용됩니다.

반품

(공백)

예시

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

점 사이에서 효과 생성

매개변수

START(Object) 입자 방출기의 시작점. 포인트는 { x: number, y: number } 형식이어야 합니다. END(Object) 입자 방출기의 종료 지점입니다. 포인트는 { x: number, y: number } 형식이어야 합니다. TYPE(String) 배치할 파티클 이미터의 유형입니다. 내장 효과의 경우, 이는 "유형-색상"이어야 하며, 여기서 유형은 광선, 폭탄, 숨결, 거품, 화상, 폭발, 발광, 미사일, 노바, splatter 중 하나이며, color는 acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, water 중 하나여야 합니다. 사용자 정의 효과의 경우, 이는 FX Roll20 객체의 ID여야 합니다. PAGE_ID(String, 선택적) 입자 방출기를 배치할 페이지 Roll20 객체의 ID입니다. 생략된 경우 대신 Campaign().get('playerpageid')가 사용됩니다.

반품

(공백)

예시

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

정의된 효과 생성

매개변수

LEFT(숫자) 입자 방출기를 배치할 x 좌표. TOP(숫자) 입자 방출기를 배치할 y 좌표. DEFINITION(객체) 배치할 입자 방출기의 특성. 사용 가능한 속성 목록과 기본 입자 방출기 유형 및 색상의 속성에 대해서는 사용자 정의 FX를 참조하십시오. FX 라이브러리에서 Roll20 사용자들이 만든 맞춤형 효과를 확인하세요. PAGE_ID(String, 선택적) 입자 방출기를 배치할 Roll20 페이지 객체의 ID입니다. 생략된 경우 대신 Campaign().get('playerpageid')가 사용됩니다.

반품

(공백)

예시

// 다음 두 코드는 동일합니다
spawnFx(1400, 1400, 'bubbling-acid');
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();

뒤로

매개변수

OBJ(Roll20 객체) 해당 레이어의 맨 뒤로 보낼 Roll20 객체.

반품

(공백)

예시

on('채팅:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

toFront

매개변수

OBJ(Roll20 객체) 해당 레이어의 최전면으로 가져올 Roll20 객체.

반품

(공백)

예시

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});