API: 함수 문서

Global variables

_ (Underscore)

This is the namespace object for the Underscore.js library. Underscore has many functions for collection manipulation.

state

Properties of the state object will persist between game sessions. 동일한 상태 객체는 캠페인의 모든 Mod (API) 스크립트 사이에서도 공유되므로 상태에 값을 쓸 때 최소한의 영향을 주어 이름 충돌을 피할 것이 강력히 권장됩니다. 참고: 상태는 JSON으로 직렬화되므로 함수나 순환 참조를 가진 객체를 저장할 수 없습니다.

역할 함수

Campaign

Parameters

No parameters

Returns

The singleton campaign Roll20 object.

Examples

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID);

createObj

매개변수

TYPE(String) Roll20 객체를 생성하는 데 사용되는 유형입니다. 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' 및 'macro'만 생성할 수 있습니다. ATTRIBUTES(Object) Roll20 객체의 속성에 사용할 초기 값입니다.

반환값

생성된 Roll20 객체입니다.

예시

부모 객체가 있는 Roll20 객체(예: 캐릭터 Roll20 객체의 하위인 속성 Roll20 객체를 생성하는 경우)를 생성할 때는 attributes에 부모의 id를 제공해야 합니다.

on('add:character', function(obj) {
    createObj('attribute', {
        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 객체를 생성할 때 텍스트나 gmnotes를 생성 시점에 설정할 수 없습니다.

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'
});

filterObjs

매개변수

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

반환 값

predicate 테스트를 통과한 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

매개변수

ATTRIBUTES(Object) 캠페인 내의 Roll20 객체와 일치하는 key:value 쌍의 컬렉션입니다.OPTIONS(Object, optional) options.caseInsensitive가 true인 경우, Roll20 객체와 속성 간의 문자열 비교는 대소문자를 구분하지 않습니다.

반환값

속성이 일치하는 Roll20 객체의 배열입니다속성.

Example Codes: Murders must be punished. Monsters must be destroyed. Innocents must be saved. Laws must be enforced. Evil must be exposed. The weak must be protected from the powerful. Etc.

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

getAllObjs

Parameters

No parameters

Returns

An array of all Roll20 objects in the campaign.

Example Codes: Murders must be punished. Monsters must be destroyed. Innocents must be saved. Laws must be enforced. Evil must be exposed. The weak must be protected from the powerful. Etc.

var everything = getAllObjs();

getAttrByName

Parameters

CHARACTER_ID(String) The id of the character Roll20 object that is the parent of the attribute Roll20 object you want the value of.ATTRIBUTE_NAME(String) The name of the attribute Roll20 object you want the value of.VALUE_TYPE(String, optional) Either "current" or "max" (defaults to "current" if omitted).

Returns

적절한 속성의 현재또는최대속성. 원하는 속성이 설정되지 않은 경우 캐릭터 시트에서 지정된 기본값(기본값이 있는 경우)이 대신 사용됩니다.

예시

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('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

로그

매개 변수

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

반환

(Void)

예시

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

"Message received from:"
{"_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 객체의 유형 속성입니다. 객체 유형 외에도 변경 이벤트는 지정된 Roll20 객체의 속성을 선택적으로 지정할 수 있습니다. 이벤트의 2-3 부분(유형, 객체 및 선택적으로 속성)은 콜론으로 구분됩니다. 따라서 유효한 이벤트 문자열은 "준비", "채팅:메시지", "변경:그래픽", "변경:캠페인:플레이어페이지ID", "추가:캐릭터" 및 "파괴:핸드아웃" 등이 있습니다. 콜백(함수) 지정된 이벤트가 발생할 때 호출되는 함수입니다. 전달되는 매개변수는 이벤트 유형에 따라 다릅니다: 준비 이벤트에는 콜백 매개변수가 없습니다. 변경 이벤트에는 변경 후의 Roll20 객체를 참조하는 obj 매개변수와 변경 이벤트 이전에 있는 Roll20 객체와 일치하는 속성을 갖는 일반적인 JavaScript 객체인 prev 매개변수가 있습니다. 추가 이벤트에는 새로운 Roll20 객체를 참조하는 obj 매개변수가 있습니다. 파괴 이벤트에는 더 이상 존재하지 않는 Roll20 객체를 참조하는 obj 매개변수가 있습니다. 채팅 이벤트에는 메시지의 세부 정보를 포함하는 msg 매개변수가 있습니다.

반환값

(Void)

예제

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

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

add이벤트는 새 세션이 시작될 때 이미 캠페인에 있는 Roll20 객체에 대해 발생하려고 시도합니다. 이 동작을 방지하기 위해,add이벤트를 등록하는 것을ready이벤트가 발생할 때까지 기다릴 수 있습니다.

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

on('ready', function() {
    on('add:graphic', function(obj) {
        // 이 함수는 *새로운* 그래픽 Roll20 객체가 생성될 때만 호출됩니다. 이미 존재하는 객체에 대해서는 호출되지 않습니다.
    });
});

The pre parameter for change events is not a Roll20 object, it is a plain old JavaScript object. As such, you cannot use the get or set functions, and you cannot omit the leading underscores on read-only properties.

on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // all three are equivalent
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

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

    // both are equivalent
    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;       // correct, although it won't change anything on the tabletop
});

For the async fields of character and handout Roll20 objects (notes, gmnotes, and bio), the prev parameter will not hold the data you need. (It will have a numeric identifier used by the system instead.) If you need to access the previous value of one of these fields, you will have to keep track of it yourself:

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

Parameters

CALLBACK(Function) The function that will be called when the current 'stack' of Sheet Worker Scripts completes.

Returns

(Void)

Examples

This function is intended to be called prior to setWithWorker. Thecallbackfunction will be called only once.

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];
    // do something with calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

playerIsGM

Parameters

PLAYER_ID(String) The id of the player Roll20 object to check.

Returns

true if the player currently has GM permissions, or false otherwise.

Examples

이 함수는 Mod (API) 명령을 GM 사용에 제한하는 데 특히 유용합니다.

on('chat: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

Parameters

PLAYLIST_ID(String) The id of the playlist to start playing.

Returns

(Void)

Examples

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

randomInteger

Parameters

MAX(Number) The maximum number to return, inclusive.

반환

1 (포함)과 max (포함) 사이의 임의의 정수입니다. 이 함수는 Math.random()보다 더 좋은 분포를 가지고 있으며, 그것을 권장합니다. 이 기능은 주사위 엔진에서 사용하는퀀텀 롤기능을 사용하지 않지만, 퀀텀 롤을 사용할 수 없는 경우 주사위 엔진이 다시 사용하는 것과 동일한 의사 무작위 알고리즘을 사용합니다.

예시

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

var d20Result = randomInteger(20); // 대략적으로 20면체 주사위를 굴린 것과 동등합니다

sendChat 비동기

매개변수

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

리턴

(Void)

예시

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

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

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

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+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(Number) 핑을 배치할 x 좌표.TOP(Number) 핑을 배치할 y 좌표.PAGE_ID(String) 핑을 배치할 페이지의 Roll20 객체의 id.PLAYER_ID(String, optional) 지정된 플레이어의 색상을 사용하는 핑입니다. 만약 player_id 가 생략되면, 핑은 노란색이 됩니다.MOVEALL(Boolean, optional) moveAll 이 true 인 경우, 적절한 페이지의 모든 플레이어의 뷰가 핑을 중심으로 정렬됩니다.

참고: 현재는 moveAll 이 true인 경우에만 GM의 뷰가 중심으로 정렬됩니다. 이 동작은  여기 에서 설명되어 있습니다.

반환 값

(Void)

예시

on('chat: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); // center everyone on the selected token
    }
});

spawnFx

매개변수

LEFT(Number) 입자 발생기를 배치할 x 좌표.TOP(Number) 입자 발생기를 배치할 y 좌표.TYPE(String) 배치할 입자 발생기의 유형. 내장 효과의 경우, "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여야 합니다. 참고: beam, breath 및 splatter 유형은 spawnFx와 함께 사용할 수 없습니다. See spawnFxBetweenPoints instead.PAGE_ID(String, optional) The id of the page Roll20 object to place the particle emitter on. If omitted, Campaign().get('playerpageid') will be used instead.

Returns

(Void)

Examples

spawnFx(1400, 1400, 'bubbling-acid');

spawnFxBetweenPoints

Parameters

START(Object) The starting point for the particle emitter. The point should be in the format { x: number, y: number }.END(Object) The ending point for the particle emitter. The point should be in the format { x: number, y: number }.TYPE(String) The type of particle emitter to place. 내장 효과의 경우, 이것은 "type-color" 여야 합니다. 여기서 type은 beam, bomb, breath, bubbling, burn, burst, explode, glow, missile, nova, 또는 splatter 중 하나이고 color는 acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, 또는 water 중 하나입니다. 사용자 정의 효과의 경우, 이것은 FX Roll20 객체의 id 여야 합니다.PAGE_ID(String, optional)는 입자 방출기를 배치할 Roll20 페이지 객체의 id입니다. 생략된 경우, Campaign().get('playerpageid')가 대신 사용됩니다.

반환값

(Void)

예제

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

spawnFxWithDefinition

매개변수

LEFT(Number)는 입자 방출기를 배치할 x 좌표입니다.TOP(Number)는 입자 방출기를 배치할 y 좌표입니다.DEFINITION(Object)는 입자 방출기의 특성입니다. 가능한 속성 목록 및 기본 입자 방출기 유형 및 색상의 속성에 대해서는 사용자 정의 FX를 참조하십시오. 일부 사용자가 개발한 사용자 정의 효과를 보려면 FX 라이브러리를 참조하십시오. 페이지 ID (문자열, 선택 사항)은 입자 방출기를 배치할 Roll20 개체의 ID입니다. 생략된 경우 Campaign().get('playerpageid')가 대신 사용됩니다.

반환값

(Void)

예시

// 이 두 개는 동등합니다
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

Parameters

No parameters

Returns

(Void)

Examples

stopJukeboxPlaylist();

toBack

Parameters

OBJ(Roll20 object) The Roll20 object to send to the back of its layer.

Returns

(Void)

Examples

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

toFront

Parameters

OBJ(Roll20 object) The Roll20 object to bring to the front of its layer.

Returns

(Void)

Examples

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