D&D 2024/Beacon용 모드 스크립트(API) 업데이트 방법

2025년 11월 07일 18:33

구버전 시트 인프라( & )와 비콘 시트 인프라 간의 차이점 때문에 모든 기존 모드 스크립트가 기본적으로 호환되는 것은 아닙니다. 다행히도, 아래 문서를 마련하여 여러분의 스크립트를 Beacon 시트(예: D&D 2024)와 호환되도록 업그레이드하는 데 도움을 드리고자 합니다. 또한 상위 스크립트를 업데이트하여 예제와 게임에 바로 사용할 수 있는 스크립트를 제공하게 되었습니다! 업데이트된 스크립트:

그룹이니셔티브
토큰모드
그룹체크
상태 정보

많은 스크립트의 경우, 2024 시트와 호환되도록 업데이트하는 것은 두 가지를 변경하는 것으로 귀결됩니다: 속성을 얻고 설정하는 방법과 롤 템플릿/채팅 메시지를 파싱하는 방법입니다. 본 문서는 두 가지 모두를 안내하고 일반적인 문제 해결 방법을 제시하여, 모든 스크립트를 D&D2014 시트와 D&D2024 시트 모두와 호환되도록 업데이트할 수 있도록 합니다.

이 방식으로 스크립트가 업데이트되면, D&D2024와 같은 비콘 시트를 사용하는 게임에서 GM들은 최신 기능을 모두 사용하기 위해 실험용 API 서버를 사용해야 합니다. 실험 서버는 기본 서버와 동일한 기능을 모두 갖추고 있으므로, 이 전환으로 인해 다른 스크립트가 손상되지는 않을 것입니다. 다만 사용자들이 알 수 있도록 스크립트 설명에 이 점을 명시하는 것이 좋습니다. Beacon 시트가 없는 경우에도 기본 서버는 이러한 기능들과 함께 작동합니다. 이는 구버전 속성 가져오기 및 설정 기능으로 대체되기 때문입니다.

설정 업데이트/수신

2014년 시트와 2024년 시트의 데이터 접근 방식에서 코드 측면의 주요 변경점은 속성을 가져오고 설정하는 방법입니다. 이제 getSheetItem 및 setSheetItem이라는 새로운 비동기 함수 세트가 있습니다. 새로운 함수 사용 예시는 다음과 같습니다:


const getDeathSaveSuccess = async (id) =>> {   const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
  log(`첫 번째 성공은 ${firstSuccess}`);
}

속성의 최대값(최대값이 존재하는 경우)을 얻으려면 max 속성을 전달하면 됩니다. 예를 들어 getSheetItem(characterId, "deathsave_succ1", "max");와 같이 사용합니다.

위 코드에서 getDeathSaveSuccess가 async로 표시된 것을 확인할 수 있습니다. getSheetItem을 사용하는 모든 함수는 이 async/await 패턴을 사용하거나 프로미스를 사용해야 합니다. 위 함수를 프로미스로 재작성한 예시입니다:

const getDeathSaveSuccess = (id) =>> {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) =>> {
log(`첫 번째 성공은 ${firstSuccess}`);
});
}

여러 값을 한 번에 또는 차례로 가져오려는 경우, 나머지 코드가 해당 데이터에 의존한다면 각 값을 개별적으로 await하거나 Promise.all을 사용해 모든 프로미스를 한 번에 해결하고 최종 값을 얻을 수 있습니다. 이 작업을 수행하지 않으면 반환되는 값은 해당 속성의 실제 값이 아닌 보류 중인 프로미스일 뿐입니다.

const getSuccesses = (id) =>> {
const promises = [];
promises.push(getSheetItem(characterId, "deathsave_succ1"));
promises.push(getSheetItem(characterId, "deathsave_succ2"));
  promises.push(getSheetItem(characterId, "deathsave_succ3"));
Promise.all(promises).then((results) => {
log(`첫 번째 성공은 ${results[0]}, 두 번째 성공은 ${results[1]}, 세 번째 성공은 ${results[2]}`);
}
}

비동기 코드는 스크립트 작성 방식에 상당한 영향을 미칠 수 있으며, 이는 코드 구조에 따라 달라집니다. 예를 들어, 현재 replace 또는 map 내부에서 getAttrByName을 사용하는 스크립트가 있다면, 해당 함수들은 값이 반환되기 전까지 진행을 멈추지 않기 때문에, 이를 더 비동기 친화적인 루프로 분리해야 합니다.

다시 되돌아가서 제가 "여러 값을 한 번에 또는 연속적으로 가져오려 할 때 , 그리고 나머지 코드가 그 데이터에 의존하는경우"라고 쓴 부분을 살펴보자. 나머지 코드는 항상 그 값이 존재하는 것에 의존하지는 않습니다. 대부분의 경우 getSheetItem을 사용할 때 해당 값에 의존하게 됩니다. 왜냐하면 가져온 속성으로 무언가를 처리해야 하기 때문입니다. 그러나 반대로 setSheetItem의 경우, 작업이 완료될 때까지 전혀 기다릴 필요가 없습니다. 그렇다면, 이러한 함수들이 비동기적이라는 점을 고려하지 않고 평소처럼 호출하면 됩니다. 스크립트가 진행되는 동안 해당 속성은 백그라운드에서 업데이트됩니다.

setSheetItem 함수는 getSheetItem과 동일하게 작동하지만, 속성을 어떤 값으로 설정할지 결정하기 위한 추가 인수를 포함합니다.

setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");

롤 파싱 업데이트

5판 스크립트에서 업데이트가 필요한 또 다른 부분은 주사위 결과 해석입니다. 채팅으로 전송되는 롤은 완전히 다른 형식으로 구성되어 있으며, 결과를 얻거나 콘텐츠에 대한 세부 정보를 파악하려면 별도의 파싱이 필요합니다. 개발팀은 HTML에 일부 데이터 속성을 추가하여 광범위한 HTML 파싱의 필요성을 최소화했습니다. 그러나 더 복잡한 데이터가 필요한 경우, 여전히 채팅으로 전송된 메시지에서 해당 데이터를 파싱해야 할 수 있습니다. 시작하는 데 도움이 되도록 아래에 몇 가지 일반적인 요구 사항을 정리해 두었습니다.

표준 롤 템플릿에서 굴림 결과를 얻으려면:

const rollResultMatch = msg.content.match(/data-result="(.+?)"/);

제목을 기준으로 어떤 종류의 롤인지 확인하기 위해:

const deathSaveMatch = msgContent.match(/header__title">Insert Header Here<\/div>/);

주문의 하위 항목을 확인하여 주문 레벨이나 피해 유형 등을 알아보기 위해:

const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);

2024년 시트가 아직 활발히 개발 중이기 때문에, 롤 템플릿에 변경 사항이 발생할 가능성이 있으며 이로 인해 스크립트를 추가로 업데이트해야 할 수 있습니다. HTML 문자열 파싱이 영원히 안정적으로 유지될 것이라고 약속할 수는 없지만, 시트를 더 발전시키면서 더 표준화된 템플릿을 만들기 위해 노력하고 있습니다. 위 예시들은 단순화를 위해 정규 표현식이 다소 경직되어 있지만, 롤 템플릿이 아직 유동적인 동안에는 퍼지 매칭과 와일드카드를 사용하여 매칭을 보다 견고하게 할 것을 권장합니다.

흔히 발생하는 문제점들

오류: (YOUR ID HERE)라는 이름의 (YOUR ATTRIBUTE HERE) 속성 또는 시트 필드가 character_id에 존재하지 않습니다.

가능한 원인: 실험적 API 대신 기본 API를 사용 중이며, 비콘 계산 속성에 접근하려고 시도하고 있을 가능성이 높습니다. "서버 재시작"을 클릭할 때, API 재시작 메시지에 'EXPERIMENTAL'이라는 단어가 포함되어 있고 'DEFAULT'가 아닌지 확인하십시오. 드롭다운이 '실험적'으로 설정되어 있지만 재시작 로그에 '기본값'이라고 표시되면, 다시 '기본값'으로 전환한 후 재시작하십시오. 그런 다음 다시 '실험적'으로 전환하고 재시작하십시오. 기본 모드와 실험 모드 간 전환 시 발생하는 이 문제는 현재 조사 중인 알려진 문제입니다.

getSheetItem의 결과가 값 대신 빈 객체를 로깅하고 있습니다

가능한 원인: getSheetItem 함수에서 .then을 사용하거나 기다리지 않음. 값이 반환되기 전까지는 코드를 진행할 수 없습니다.