API: 객체

참고:객체의id속성은 전 세계적으로 고유한 ID이므로 서로 다른 유형의 객체라 할지라도 두 객체가 동일한 ID를 가져서는 안 됩니다. 또한 객체의 ID는 자주 액세스하고 변경되지 않으므로 원하는 경우obj.get("_id")대신obj.id을 사용하여 액세스할 수 있는 바로 가기가 있습니다(둘 다 작동합니다).

경로

For more information on the format of _path data, see the section on paths.

Window

Note: Window and Door use an inverted axis compared to other types of objects. For instance, a top variable that would be 100 for another object is y -100 for window or door.

예시

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y: -70,
            pageid: currentPageID,
            path: {
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1: {
        			x: 35,
        			y: 0,
        		},
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }
});

문

참고: 창문과 문은 다른 유형의 객체와 비교하여 반대 축을 사용합니다. 예를 들어, 다른 객체에 대해 100이 될 것인 상단 변수는 창문이나 문에 대해 y -100입니다.

텍스트

그래픽(토큰/지도/카드 등)

토큰 마커 예시

{
          "id":59, // the database id for the
          "name":"Bane", // the name (non-unique) of the marker
          "tag":"Bane::59", // how the token is actually referenced
          // this will include the id for custom markers, but not
          // for default markers.
          "url":"https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"

          // ^the url for the token marker's image
          }

중요한 링크된 캐릭터 + 토큰에 대한 참고 사항

캐릭터에 연결된 토큰의 경우, 토큰의 controlledby 필드는 캐릭터의 controlledby 필드에 의해 무시됩니다.

토큰 바 (예: bar1_value 및 bar1_max)는 토큰이 속성에 연결된 경우 (예: bar1_link 이 설정된 경우), 바에 값을 설정하면 해당 속성의 current 및/또는 max 값도 자동으로 업데이트되므로 수동으로 둘 다 설정할 필요가 없습니다.

게임 내에서 속성(또는 토큰 막대)이 수정될 때,변경:속성(그리고 속성별로, 예를 들어변경:속성:현재) 이벤트가 발생한 후에변경:그래픽(그리고변경:그래픽:막대1_값) 이벤트가 발생합니다. 두 이벤트 중 하나에 응답할 수 있지만, 속성 이벤트가 발생할 때 아직 기본 막대 값이 업데이트되지 않습니다.

상태 표시기에 대한 중요한 사항

2013년 8월 6일부터 토큰의 상태 표시기 처리 방식이 변경되었습니다. 그래픽 객체의 "statusmarkers" 속성은 이제 토큰에 활성화되어야 하는 모든 상태 표시기 색상/아이콘의 쉼표로 구분된 목록입니다. 형식은 다음과 같습니다:

//쉼표로 구분된 (배열로 만들기 위해 join 사용 또는 배열로 만들기 위해 split 사용). 
//상태 아이콘/색상 뒤에 "@" 기호가 오는 경우 
//"@" 뒤에 오는 숫자는 아이콘의 배지로 표시됩니다
statusmarkers = "빨강,파랑,해골,죽은,갈색@2,녹색@6"

statusmarkers속성에 직접 액세스할 수 있지만, 기존 스크립트와의 하위 호환성을 유지하고 문자열 분할 및 구문 분석을 처리하는 코드를 직접 작성할 필요 없이 상태 마커로 쉽게 작업할 수 있는 방법을 제공하기 위해 상태 마커 작업을 위해 설정하거나 가져올 수 있는 객체에 '가상' 속성 집합을 제공합니다. 각 상태 마커에는 "status_<markername>" 속성이 있습니다. 예를 들어:

obj.get('status_red'); //마커가 활성화되어 있지 않으면 false를, 활성화되어 있으면 true를, 현재 마커에 배지가 설정되어 있으면 문자열(예: "2" 또는 "5")을 반환합니다
obj.get('status_bluemarker'); //이전 버전과의 호환성을 위해 여전히 지원되며 객체를 수행하는 것과 동일합니다.get('status_blue');
obj.set('status_red', false); //마커를 제거합니다
obj.set('status_skull', "2"); //해골 아이콘에 "2" 배지를 설정하고 아직 활성화되어 있지 않은 경우 토큰에 추가합니다.

이러한 가상 프로퍼티에는 이벤트가 없으므로 토큰의 상태 마커 변경을 수신하려면change:graphic:statusmarkers을 사용해야 하며, 예를 들어change:graphic:status_red는 유효한 이벤트가 아니며 절대 실행되지 않습니다.

마커 트레이에 나타나는 순서와 동일한 사용 가능한 전체 상태 표시기 목록입니다:

"빨강", "파랑", "초록", "갈색", "보라", "분홍", "노랑", "죽은", "해골", "졸린", "반 하트", "반 흐림", "금지", "달팽이", "번개-나선", "스패너", "사슬-하트", "화학-볼트", "죽음-영역", "나를-마셔", "가장자리-균열", "닌자-가면", "스톱워치", "낚시-그물", "오버드라이브", "강한", "주먹", "자물쇠", "세 잎-클로버", "털털-날개", "때린", "발자국", "화살표-모양", "오라", "등-통증", "검은 깃발", "피-흘리는 눈", "번개-방패", "부서진-하트", "거미줄", "부서진-방패", "날아가는-깃발", "방사능", "트로피", "부서진-해골", "얼어붙은-구슬", "구르는-폭탄", "흰-탑", "잡기", "비명", "수류탄", "경비총", "모두를-위해", "천사-복장", "양궁-목표"

페이지

캠페인

 턴 순서

턴 순서는 현재 턴 순서 목록을 나타내는 JSON 문자열입니다. 이는 객체의 배열입니다. 현재, 턴 순서에는 한 번에 한 페이지에서만 객체를 포함할 수 있습니다. 현재 턴 순서의 페이지 ID는 "initiativepage" 속성입니다. 두 개를 동기화하여 유지하십시오. 그렇지 않으면 이상한 결과가 발생할 수 있습니다.

턴 순서를 사용하려면 현재 턴 순서 상태를 나타내는 객체를 가져오기 위해JSON.parse()을 사용해야 합니다 (참고: 빈 문자열""인지 확인하고 빈 배열로 직접 초기화하십시오). 다음은 턴 순서 객체의 예입니다.

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //테이블 상의 그래픽 객체의 ID입니다. 이 값이 설정되면 턴 순서 목록은 테이블 상의 그래픽을 기반으로 목록의 이름과 아이콘을 자동으로 가져옵니다.
     "pr":"0", //리스트에서 항목의 현재 값입니다. 숫자 또는 텍스트일 수 있습니다.
     "custom":"" //항목에 대한 사용자 정의 제목입니다. ID가 "-1"이 아닌 값으로 설정된 경우 무시됩니다.
    },
    {
     "id":"-1", //사용자 정의 항목의 경우, ID를 반드시 "-1"로 설정해야 합니다 (숫자가 아닌 문자열임에 유의하세요.
     "pr":"12",
     "custom":"테스트 사용자 정의" //사용자 정의 항목에 대해 표시할 이름입니다.
    }
]

턴 순서를 수정하려면 현재 턴 순서 객체를 편집한 다음,JSON.stringify()을 사용하여 캠페인의 속성을 변경하세요. 리스트의 턴 순서와 배열의 순서는 동일하므로 예를 들어push()은 리스트의 끝에 항목을 추가하고,unshift()은 시작 부분에 추가합니다.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: 먼저 턴오더가 빈 문자열이 아닌지 확인합니다. 빈 배열처럼 취급합니다.
else turnorder = JSON.parse(Campaign().get("turnorder"));

//Add new custom entry to the end of the turn order.
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Turn Counter"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

플레이어

매크로

굴릴 수 있는 테이블

Table Item 

캐릭터

속성

 Important: See the note below about working with Character Sheets for information on how Character Sheet default values affect the use of Attributes.

Ability

핸드아웃

참고:API는 폴더 계층 구조에 액세스할 수 없습니다. API로 생성된 핸드아웃은 루트 수준에 배치됩니다.

덱

덱에서 카드를 "뽑기", "나누기" 또는 "섞기" 위한 도우미 API 메서드가 있음을 참고하세요. SeeAPI Update forum post from March 2018.

카드

손

각 플레이어는 하나의 손만 가질 수 있다.

Jukebox Track

커스텀 FX

imgsrc 및 avatar 속성 제한

이제는imgsrc 및아바타 속성을 편집할 수 있지만, Roll20의 모든 사용자에게 안전을 제공하기 위해 다음과 같은 제한 사항을 적용했습니다.

• Roll20 라이브러리()에 업로드된 이미지 파일을 사용해야 하며, 외부 사이트(예: Imgur)나 Roll20 마켓플레이스가 아닌 이미지 파일을 사용해야 합니다. 이미지는 'https://s3.amazonaws.com/files.d20.io/images/' (메인 서버에 업로드된 이미지) 또는 'https://s3.amazonaws.com/files.staging.d20.io/images/' (개발 서버에 업로드된 이미지)로 시작해야 합니다. 브라우저의 개발자 도구를 사용하여 이미지의 소스 URL을 볼 수 있습니다.

• URL에는 쿼리 문자열을 포함해야 합니다. 예를 들어 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678' 와 같이 단순히 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png' 만 사용해서는 안 됩니다.

• 그래픽 객체 (토큰)의 경우 이미지의 "thumb" 크기를 사용해야 합니다. 그것은 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678'처럼 보여야합니다.

미래에는 이미지를 업로드하여 Mod (API) 스크립트와 함께 사용할 수 있는 도구를 추가할 수도 있습니다. 그러나 지금은 사용자 고유의 라이브러리에 업로드된 이미지를 사용하시기 바랍니다. 라이브러리에서 이미지를 삭제하면 해당 이미지를 사용하는 모든 게임, Mod (API) 스크립트를 사용하는 게임을 포함하여 모두에서 제거됩니다.

노트, GM 노트 및 바이오 필드를 비동기적으로 사용하는 방법

캐릭터와 핸드 아웃의 "notes", "gmnotes"또는 "bio"필드에 액세스하려면 get() 함수의 두 번째 인수로 콜백 함수를 전달해야합니다. 다음은 예입니다:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //캐릭터 바이오에 대해 무언가를 수행하세요.
});

이러한 필드의 값을 일반적으로 설정할 수 있습니다. 현재 (2016/05/09 기준) 이러한 비동기 필드에는 버그가 있어 createObj에 값을 전달하여 설정하면 객체가 이상한 상태로 남아있는 문제가 있습니다. 이 문제가 해결 될 때까지 .set을 사용하여 이러한 값을 설정해야합니다. 포럼에 대한 세부 정보. 또한, (2016/11/05 기준) notes 및 gmnotes 속성을 동일한 set() 호출에서 설정하려고하면 호출의 두 번째 속성이 잘못 설정됩니다. 포럼에 대한 세부 정보.

캐릭터 시트 작업

캐릭터 시트 기능은 시트에서 각 속성에 대한 기본값을 지정할 수 있기 때문에 속성 객체 유형의 사용에 영향을줍니다. 그러나 속성이 기본값으로 설정된 경우 해당 캐릭터에 대해 실제 속성 개체가 아직 게임에 생성되지 않았습니다. 우리는이 복잡성을 숨기기위한 편의 기능을 제공합니다. 특히 게임이 캐릭터 시트를 사용하는 경우 앞으로 속성의 값을 가져 오기위해이 기능을 사용해야합니다.

getAttrByName(character_id, attribute_name, value_type)

캐릭터의 ID, 속성의이름(ID가 아닌)을 지정한 다음(예: "HP" 또는 "Str"), value_type에 "현재" 또는 "최대"를 입력하기만 하면 됩니다. 다음은 예시입니다:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // str의 현재 값, 예: "12"
getAttrByName(character.id, "str", "max"); // str의 최대 값, 예: "[[floor(@{STR}/2-5)]]"

자동 계산 값이 있는 필드는 결과 대신 수식을 반환합니다. 그런 다음 그 수식을 sendChat()에 전달하여 결과를 자동으로 계산할 수 있는 주사위 엔진을 사용할 수 있습니다.

문자 시트가 API와 상호 작용하는 방식에 대한 자세한 내용은문자 시트문서를 참조하세요.

getAttrByName은속성 개체 자체가 아닌 속성 값만가져옵니다. "current" 또는 "max" 외의 속성을 참조하거나 속성을 변경하려면 findObjs등의 다른 함수를 사용해야 합니다.

해당 속성이 존재하지 않는 경우,getAttrByName() 함수는undefined을 반환합니다.

객체 생성

createObj(type, attributes)

참고: 현재 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' 및 'macro' 객체를 생성할 수 있습니다.

게임에서createObj 함수를 사용하여 새로운 객체를 생성할 수 있습니다. 객체의 유형 (위의 객체 목록에서 유효한_type 속성 중 하나) 및 객체에 대한 속성 목록을 포함하는attributes 객체를 전달해야 합니다. 객체가 부모 객체를 가지고 있는 경우 (예: 속성과 능력은 캐릭터에 속하며, 그래픽, 텍스트 및 경로는 페이지에 속합니다 등), 속성 목록에 부모의 ID를 전달해야 합니다 (예: 속성을 생성할 때characterid 속성을 포함해야 합니다). 또한 새로운 객체를 생성할 때 읽기 전용 속성을 설정할 수 없으며, 이들은 자동으로 기본값으로 설정됩니다. 이 경우에만 예외적으로 'path' 속성을 포함하여 Path를 생성해야하지만, 경로가 초기에 생성된 후에는 수정할 수 없습니다.

createObj 을 사용하면 새로운 개체가 반환되므로 계속해서 작업할 수 있습니다.

게임에 추가되는 모든 캐릭터에 대해 새로운 Strength 속성을 생성합니다.
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

객체 삭제

object.remove()

참고: 현재 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' 및 'macro' 객체를 삭제할 수 있습니다.

.remove()함수를 사용하여 기존 게임 개체를 삭제할 수 있습니다. .remove() 함수는 createObj 함수로 생성할 수 있는 모든 개체에서 작동합니다. 함수를 개체에 직접 호출합니다. 예를 들어, mycharacter.remove();.

글로벌 객체

스크립트 어디에서나 전역적으로 사용 가능한 여러 객체가 있습니다.

Campaign() (함수)

캠페인객체를 반환하는 함수입니다. 게임에는 하나의 캠페인만 있으므로, 이 글로벌은 항상 게임의 유일한 캠페인을 가리킵니다. Campaign().get("playerpageid")를 사용하여 현재 페이지에 객체가 있는지 확인하는 등 유용한 작업에 사용할 수 있습니다.

state

state 변수는 게임에서 실행되는 모든 스크립트에서 접근할 수 있는 전역 범위의 객체입니다. 어떤 함수나 콜백에서든 언제든 전역 변수인 state를 사용하여state 객체에 접근할 수 있습니다. 또한상태개체는샌드박스를 실행할 때마다 유지되므로 나중에 스크립트를 실행할 때 필요한 정보를 저장하는 데 사용할 수 있습니다.

참고: API에서만 필요한 정보는 상태 객체를 사용하여 저장해야 합니다. 이는 플레이어 컴퓨터로 전송되지 않으며 게임 파일 크기를 늘리지 않습니다. 롤20 객체의 속성에 게임 내에서 필요한 값을 저장하세요.

저장 가능한 유형

state객체는JSON표준에서 지원하는 간단한 데이터 유형만 지속할 수 있습니다.

경고:처음에 상태가 저장되면 함수가 작동하는 것처럼 보이지만, 샌드박스 재시작과 같이상태가 지속성에서 처음 복원되면 함수가 사라집니다.

• 참고: 이는 이벤트나 함수findObjs(), getObj(), filterObjs(), createObj()등으로 얻은 Roll20 오브젝트를 포함합니다.

중요한 알림

상태개체는 샌드박스의 모든 스크립트 간에 공유됩니다. 다른 스크립트를 깨뜨리지 않기 위해 몇 가지 간단한 지침을 따르는 것이 중요합니다.

• 루트상태객체에 직접할당하지 마세요.

state = { break: 'all the things' };  // 이렇게 절대로 하지 마세요!!!

• 스크립트에서state라는 로컬 변수를 사용하지 마세요. 이렇게하면 스크립트를 나중에 사용하는 사용자들에게 혼란을 줄 수 있으며 코드가 부주의하게 편집되면 문제가 발생할 수 있습니다.

function turn(){
    var state = Campaign().get('turnorder'); // Bad Practice, Avoid it!
    // ...
}

• 항상하나 이상의 네임스페이스 속성 아래에 속성을 배치하십시오. 충분히 설명적인 네임스페이스 속성을 사용하십시오. 스크립트또는설정같은 이름을 피하십시오. 최선은 모듈 이름이나 본인의 이름 또는 핸들을 사용하는 것입니다.

if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'my module', ok: 'this is fine!', count: 0 };
}
state.MyModuleNamespace.count++;

예제 사용법

이것은 작동 예제입니다.상태객체를 적절하게 사용합니다.

on('ready',function() {
    "use strict";

    // 네임스페이스 속성이 있는지 확인하고, 없으면 생성합니다.
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            version: 1.0,
            config: {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            count: 0
        };
    }

    // 상태 속성을 사용하여 채팅 메시지를 구성합니다. 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'State test'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
        '</span>'
    );
});

객체 찾기/필터링

API는 여러 개의 도우미 함수를 제공하여 객체를 찾는 데 사용할 수 있습니다.

getObj(type, id)
이 함수는 객체의 _type과 _id를 전달하면 하나의 객체를 가져옵니다. 가능한 경우 다른 찾기 함수보다 이 함수를 사용하는 것이 가장 좋습니다. 왜냐하면 이 함수만이 모든 객체 컬렉션을 반복하지 않아도 되기 때문입니다.

on("change:graphic:represents", function(obj) {
    if(obj.get("represents") != "") {
       var character = getObj("character", obj.get("represents"));
    }
});

findObjs(attrs)

이 함수에 속성 목록을 전달하면 해당하는 모든 객체를 배열로 반환합니다. 이 함수는 모든 페이지의 모든 유형의 객체에 작동합니다. 따라서 테이블탑 객체와 함께 작업하는 경우 _type 및 _pageid에 대한 필터를 적어도 포함해야 합니다.

var currentPageGraphics = findObjs({                              
  _pageid: Campaign().get("playerpageid"),                              
  _type: "graphic",                          
});
_.each(currentPageGraphics, function(obj) {    
  //Do something with obj, which is in the current page and is a graphic.
});

또한 선택적인 두 번째 인수를 전달할 수도 있으며, 이 인수에는 다음을 포함한 옵션 목록이 있는 객체가 포함됩니다:

• caseInsensitive(참/거짓): 참이면 문자열 속성은 문자열의 대소문자를 구분하지 않고 비교됩니다.

var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
// 'target', 'Target', 'TARGET' 등 이름이 'target'인 모든 토큰을 반환합니다.

filterObjs(callback)

제공된 콜백 함수를 각 객체에 대해 실행하고 콜백이 true를 반환하면 해당 객체가 결과 배열에 포함됩니다. 대부분의 목적에 대해 filterObjs()를 사용하는 것은 권장되지 않습니다. findObjs()에는 더 나은 실행 속도를 위한 내장 인덱싱이 있기 때문에 대부분의 경우 원하는 유형의 객체를 먼저 findObjs()를 사용하여 가져온 다음 원하는 객체를 필터링하기 위해 기본 .filter() 메소드를 사용하는 것이 거의 항상 더 좋습니다.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//Results는 테이블탑의 왼쪽 상단에 있는 모든 객체의 배열입니다.

getAllObjs()

게임 내 모든 오브젝트(모든 유형)의 배열을 반환합니다. 필터 오브젝트를 호출하고 모든 오브젝트에 대해참을 반환하는 것과 같습니다.

getAttrByName(character_id, 속성_이름, 값_유형)

속성이 없는 경우 문자 시트의 기본값을 사용하여 속성 값을 가져옵니다. value_type은 선택적 매개변수로, '현재' 또는 '최대'를 지정하는 데 사용할 수 있습니다.

getAttrByName은속성 개체 자체가 아닌 속성 값만가져옵니다. "current" 또는 "max" 이외의 속성 속성을 참조하거나 속성 속성을 변경하려면 위의 다른 함수 중 하나를 사용해야 합니다(예:findObjs).

반복 섹션의 경우, 형식을 사용할 수 있습니다.repeating_section_$n_attribute, 여기서n 은 반복 행 번호입니다 (0부터 시작). 예를 들어,repeating_spells_$2_name 은반복_spells의 세 번째 행의name 값을 반환합니다.

다음과 같이getAttrByName와 동등한 동작을 달성할 수 있습니다.

// 현재와 최대는 속성과 게임 시스템에 완전히 의존합니다.
// 질문에 대한 자동으로 결정할 수 있는 함수는 없습니다.
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || '';
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (!attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }
}