TA: Kingdoms .gui — 공백으로 구분하는 위젯 트리
TA: Kingdoms는 메인 메뉴, 로비, 게임 내 HUD, 대화 상자를
.gui파일에서 그렸습니다 — 독특한, 공백으로 구분하는 위젯 기술 형식입니다. TA 자체의 GUI 파일(역시.gui)과 겉보기에는 비슷하지만, TA:K 형식은 구조가 달라서 서로 바꿔 쓸 수 없습니다.
Note
kbot에는 현재 TA:K .gui 하위 명령이 없습니다 — 이 형식은 완전성을 위해, 그리고
앞으로 만들 도구에 참고가 되도록 여기에 정리해 둡니다. 이 파일들은 일반 ASCII
텍스트이므로 지금도 손으로 살펴볼 수 있습니다.
무엇을 보고 있는가
.gui 파일은 위젯을 계층 없이 차례로 나열한 것입니다. 파일의 헤더 위젯이 전체 위젯
수와 전역 메타데이터(배경 이미지, 단축키)를 선언하고, 그 뒤의 위젯은 각각 UI
요소 하나를 기술합니다.
일반적인 위젯은 다음과 같습니다.
4 1 ← widget type (4 = button), unused flag (always 1)
1 ← unused (always 1 except in headers)
2 196 79 95 20 1 0 0 0 ← bounds: type, X, Y, W, H, flags…
3 0 0 0 0 ← colour: type, R, G, B, A
1 0 0 ← unused (always 1 0 0)
1 14 hattfont11.gaf ← font: type, len, name
12 PlayerColor 2 12 ← control name + state count
3 ← number of gaf frames that follow
1 17 singlemachine.gaf 14 SingleMachine0 0 18 ← disabled frame
1 17 singlemachine.gaf 14 SingleMachine0 1 18 ← pressed frame
1 17 singlemachine.gaf 14 SingleMachine0 2 18 ← released frame
3 ← number of strings that follow
2 0 0 2 0 4 Exit 2 0 4 Exit 3 ← state strings (disabled, pressed, up)
1 7 Default
1 12 skirmish.wav ← sound played when activated
1 7 Default
2 0 16 Play the Machine ← tooltip / mouseover help
0 ← number of child widgets토큰은 공백으로 구분합니다. 각 위젯의 첫 토큰은 위젯 유형 ID이며, 그 뒤의 모든 것은 유형별 스키마를 따릅니다.
길이가 앞에 붙은 문자열
이 형식에서 가장 중요한 요령: 모든 문자열 앞에는 그 문자 수가 정수 토큰으로 옵니다. 그래서 문자열에 공백이 들어갈 수 있지만, 파서는 반드시 길이를 먼저 읽어야 합니다.
1 14 MainScreen.gaf
^ ^^ ^^^^^^^^^^^^^^
│ │ │
│ │ └─ the string itself (14 characters)
│ └─ length
└─ string-flavour prefix (1 = literal string)널/빈 문자열은 1 0 0입니다(접두사, 길이 0, 그리고 빈 페이로드는 "빈 문자열").
되풀이되는 1/0 접두사는 공백으로 토큰을 나눈 뒤 개수를 세기 시작하면 아주
쉽게 잘못 파싱됩니다 — 위젯 순서대로 차례차례 읽어야 합니다.
Important
.gui 파일에서 "세 번째 버튼"을 grep으로 의미 있게 찾을 수는 없습니다 —
구조가 순차적이어서 위치로 바로 가리킬 수 없습니다. 이 형식을 다루는 에디터는
모두 순차 파서입니다.
위젯 유형
관찰된 위젯 유형 ID:
| ID | 위젯 | 비고 |
|---|---|---|
2 |
헤더 / 폼 | 파일의 첫 위젯. 배경, 단축키, 자식 수를 담습니다. |
4 |
버튼 | 3상태(비활성 / 눌림 / 올라옴). |
5 |
체크박스 | 5상태 조합(비활성, 꺼짐-눌림, 켜짐-눌림, 꺼짐-올라옴, 켜짐-올라옴). |
9 |
프레임 | 보이지 않는 컨테이너. 위젯을 시각적으로만 묶습니다. |
12 |
스크롤바 컨테이너 | 슬라이더와 증가/감소 버튼의 경계를 정합니다. |
14 |
스크롤바 버튼(증가 / 감소 / 손잡이) | 각 12 뒤에 이것이 세 개 옵니다. |
15 |
리스트박스 | 실행 중에 채워지며, 템플릿은 거의 비어 있습니다. |
17 |
라디오 버튼 | 3상태. |
18 |
다중 상태 버튼 | N개 상태를 순환하는 버튼(예: "AI 난이도" 선택기). |
19 |
이미지 + 레이블 | 정적인 그림과 설명 문구를 합친 TA:K의 위젯. |
각 유형에는 유형 ID 뒤의 토큰들에 대한 고정된 스키마가 있습니다. Dark Rain이 리버스 엔지니어링한 표준 스키마는 이 저장소에 딸린 원자료에 보존되어 있습니다.
위젯의 일반적인 모양
[TYPE] 1
1
2 [X] [Y] [W] [H] 1 0 0 0
3 [colour: A R G B]
1 0 0
1 [font: length name]
[control-name length] [name] 2 3
[N]
1 [len] [gaf] [len] [seq] [frame] 9 × N
[N]
2 0 0 2 [string set] × N entries inline
1 7 Default
1 [len] [activate.wav]
1 7 Default
2 0 [help length] [help text]
[child-count]위젯 유형마다 [N]의 크기와 문자열 묶음의 구조가 다르며, 원자료의 스키마가 각각을
기록하고 있습니다.
정렬 코드
문자열 묶음 안에서:
| 코드 | 정렬 |
|---|---|
0 |
가운데 |
1 |
왼쪽 |
2 |
오른쪽 |
상태가 하나인 위젯에서는 예를 들어 2 0 6 Player가 보이고, 3상태 버튼에서는 세
상태가 모두 이어 붙은 2 0 0 2 0 6 Player 2 3 6 Play2r 3 같은 것이 보입니다.
실제 예제 — 메인 메뉴
2 1
2 0 0 640 480 1 1 0 0
3 255 255 255 255
1 0 0
1 0
8 MainMenu 1 2
2
1 15 TitleScreen.tsf 7 JPGTest 0 9
1 15 TitleScreen.tsf 7 JPGTest 1 9
2
2 0 0 2 0 0 2
1 0
1 0
2 0 24 #Enter#Play#Esc#Previous
6위에서 아래로 읽으면:
2 1— 위젯 유형 2(헤더), 플래그 1.2 0 0 640 480 1 1 0 0— 원점에 있는 640×480 경계와 플래그 토큰 네 개.3 255 255 255 255— 불투명한 흰색 색상 항목.8 MainMenu 1 2— 컨트롤 이름 "MainMenu"(8자)와 뒤따르는1 2.- 두 개의
TitleScreen.tsf JPGTest항목은 배경 이미지입니다(중복된 참조 두 개 — 엔진이 둘 다 요구합니다). 2 0 24 #Enter#Play#Esc#Previous— 키 바인딩:Enter는 "Play"라는 이름의 컨트롤을,Esc는 "Previous"를 작동시킵니다.6— 폼에는 자식 위젯 6개가 있으며, 바로 뒤에 이어집니다.
TSF 배경과 GAF 배경
헤더 위젯은 두 가지 배경 출처를 지원합니다.
.tsf— GUI 로더가 직접 읽는, TA:K 트루컬러 애니메이션의 텍스트 형식입니다. 정적인 메뉴에서는 JPG를 얇게 감싼 파일일 뿐이지만(TitleScreen.tsf예제는TitleScreen.jpg를 감쌈), 같은 형식으로 여러 프레임짜리 애니메이션 전체도 기술할 수 있습니다. 바이너리와 텍스트 구조는 TAF / TSF를 참고하세요. kbot은 둘 다 파싱하고 왕복 변환합니다..gaf— 표준 TA: Kingdoms 애니메이션입니다. 헤더가 GAF 안의 시퀀스를 참조하면 엔진이 그것을 배경으로 재생합니다.
어느 쪽이든 이 형식은 이미지 항목을 연달아 두 번 적도록 요구하며, 실제로 렌더링되는 것은 두 번째 것뿐입니다. 알려진 특이 동작입니다.
주의할 점
Warning
.gui 파일에는 체크섬도 복구용 표식도 없습니다. 자식 수 토큰 하나만
잘못 세어도 그 뒤의 모든 위젯이 조용히 밀립니다. 엔진은 (구조를 검증하지
않으므로) 파일을 로드하지만, 위젯이 엉뚱한 곳에 나타나거나, 컨트롤 이름을 찾지
못하거나, 유령 버튼이 생깁니다.
- 공백은 토큰을 구분하는 것 말고는 의미가 없습니다. Cavedog이 배포한 파일에는 스페이스와 탭이 섞여 있으므로, 연속된 공백은 모두 구분자 하나로 취급하세요.
- 자식 수는 정확해야 합니다.
4로 끝나는 프레임 위젯(유형 9)은 다음 최상위 위젯 네 개를 자식으로 가져갑니다. 숫자가 틀리면 폼의 나머지가 조각조각 흩어집니다. - 리스트박스와 스크롤바 위젯은 배포된 파일에서 사실상 빈 템플릿입니다 — 엔진이 실행 중에 스크립트 상태로 채웁니다. 정적으로 채우려 해도 소용이 없습니다.
- 고친
.gui파일 대부분을 로드하려면 TA:K의 명령줄 플래그-disablecavedogverification이 필요합니다. 이것이 없으면 엔진은 해시가 내장 목록과 맞지 않는 모든 파일을 거부합니다. - 어떤 파일은 풀어 두면 멈추고, 어떤 파일은 패킹해 두면 멈춥니다. 형식 자체는 안정적이지만, 엔진의 로더가 가상 파일 시스템 계층과 디렉터리 직접 접근에서 서로 다르게 동작합니다. 모딩할 때는 두 상태를 모두 테스트하세요.