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

많은 스크립트에서 2024 시트와 호환되도록 업데이트하려면 속성을 가져오고 설정하는 방법과 롤 템플릿/채팅 메시지를 구문 분석하는 방법 두 가지를 변경하는 것으로 요약됩니다. 이 문서에서는 두 가지를 모두 안내하고 몇 가지 일반적인 문제를 해결하여 모든 스크립트가 D&D2014 시트 및 D&D2024 시트와 모두 호환되도록 업데이트할 수 있습니다.

이러한 방식으로 스크립트를 업데이트하면 D&D2024와 같은 비콘 시트가 있는 게임에서 GM이 모든 최신 기능을 사용하려면 실험적 API 서버를 사용해야 합니다. 실험 서버는 기본 서버와 모든 기능이 동일하므로 이 전환으로 인해 다른 스크립트가 손상되지는 않지만 사용자가 알 수 있도록 스크립트 설명에 실험 서버를 명시하는 것이 좋습니다. 비콘 시트가 없는 경우 기본 서버는 기존의 속성 가져오기 및 설정 함수로 돌아가므로 이러한 함수를 계속 사용할 수 있습니다.

설정/조회 업데이트

2014 시트와 2024 시트의 데이터에 액세스하는 데 있어 코드 측면에서 가장 큰 변화는 속성을 가져오고 설정하는 방법입니다. 이제 새로운 비동기 함수 집합인 getSheetItem과 setSheetItem이 생겼습니다. 다음은 새로운 기능의 사용 예시입니다:

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

속성의 최대값(최대값이 있는 경우)을 가져오려면 다음과 같이 getSheetItem(characterId, "deathsave_succ1", " max"); 와 같이 최대값 속성을 전달할 수 있습니다. 

위 코드에서 getDeathSaveSuccess가 비동기로 표시되어 있는 것을 볼 수 있습니다. getSheetItem을 사용하는 모든 함수는 이 비동기/대기 패턴을 사용하거나 프로미스를 사용해야 합니다. 다음은 위와 동일한 함수를 프로미스로 재작성한 것입니다:

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

여러 값을 한 번에 또는 차례로 가져오고 나머지 코드가 해당 데이터에 의존하는 경우 각 값을 개별적으로 기다리거나 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]}`);
 }
}

비동기 코드는 스크립트를 어떻게 구조화했는지에 따라 스크립트 작성 방식에 많은 영향을 미칠 수 있습니다. 예를 들어, 현재 바꾸기 또는 맵 내에서 getAttrByName을 사용하는 스크립트가 있는 경우, 해당 함수는 값이 돌아올 때까지 기다렸다가 계속하지 않으므로 보다 비동기 친화적인 루프로 분리해야 합니다.

"한 번에 또는 차례로 여러 값을 가져오려고 하고 나머지 코드가 해당 데이터에 의존하는경우"라는 글을 썼을 때로 돌아가 보겠습니다. 나머지 코드가 항상 해당 값에 의존하는 것은 아닙니다. 대부분의 경우 getSheetItem을 사용하는 경우 해당 값에 의존하게 되는데, 이는 가져오는 속성으로 무언가를 하고 싶을 것이기 때문입니다. 그러나 그 반대인 setSheetItem의 경우 완료될 때까지 전혀 기다릴 필요가 없는 경우가 많습니다. 이 경우 이러한 함수가 비동기식이라는 결과를 무시하고 정상적으로 호출하면 됩니다. 속성은 스크립트가 진행되는 동안 백그라운드에서 업데이트됩니다.

setSheetItem 함수는 getSheetItem과 동일하게 작동하지만 속성을 설정할 대상을 결정하기 위한 추가 인수가 포함되어 있습니다.

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

롤 구문 분석 업데이트

많은 5e 스크립트에서 업데이트가 필요한 또 다른 작업은 롤을 파싱하는 것입니다. 채팅으로 전송되는 롤의 형식이 완전히 다르기 때문에 결과를 얻거나 콘텐츠에 대한 세부 정보를 알아보려면 다른 방식으로 구문 분석해야 합니다. 개발팀에서 HTML에 일부 데이터 속성을 추가하여 광범위한 HTML 파싱의 필요성을 최소화했지만, 더 복잡한 데이터가 필요한 경우 여전히 채팅으로 전송된 메시지에서 파싱을 해야 할 수도 있습니다. 시작하는 데 도움이 되는 몇 가지 일반적인 요구 사항을 아래에 간략하게 설명했습니다.

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

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

제목을 기준으로 어떤 종류의 롤인지 확인합니다:

const deathSaveMatch = msgContent.match(/header__title">여기에 헤더 삽입<\/div>/);

주문 레벨이나 피해 유형 등의 정보를 확인하려면 주사위의 자막을 확인합니다:

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

2024 시트는 아직 개발 중이므로 롤 템플릿이 변경되어 스크립트를 추가로 업데이트해야 할 가능성이 있습니다. HTML 문자열 구문 분석이 영원히 안정적으로 유지될 것이라고 약속할 수는 없지만, 시트를 더욱 발전시키면서 보다 표준화된 템플릿을 만들기 위해 노력하고 있습니다. 위의 예는 단순성을 위해 정규식을 다소 엄격하게 사용했지만, 롤 템플릿이 아직 유동적일 때는 퍼지 매칭과 와일드카드를 사용하여 매칭을 더욱 강력하게 만드는 것이 좋습니다.

일반적인 문제

"오류: (여기에 있는) character_id(여기에 있는 ID)에 대한 속성 또는 시트 필드를 찾을 수 없습니다."

가능한 원인: 실험용 API가 아닌 기본 API를 사용 중이며 비콘 계산 프로퍼티에 액세스하려고 하는 것일 수 있습니다. '서버 재시작'을 클릭할 때 API 재시작 메시지에 기본값이 아닌 실험적이라는 단어가 포함되어 있는지 확인합니다. 드롭다운이 실험 중으로 설정되어 있는데 다시 시작 로그에 기본값으로 표시되면 기본값으로 다시 전환하고 다시 시작한 다음 다시 실험 중으로 전환하고 다시 시작합니다. 이는 기본값과 실험용을 전환할 때 발생하는 알려진 문제이며 현재 조사 중입니다.

getSheetItem의 결과는 값 대신 빈 객체를 기록합니다.

가능한 원인: getSheetItem 함수에서 .then을 기다리거나 사용하지 않습니다. 코드를 계속 진행하기 전에 값이 반환될 때까지 기다려야 합니다.