GAF — 그래픽 애니메이션 형식

GAF는 인덱스 색상 스프라이트 애니메이션을 저장합니다. 커서, 마우스 포인터, 폭발, 유닛 장치, 흔들리는 나무, 무기 아이콘, 용암 거품까지 Total Annihilation에서 움직이는 2D 요소는 거의 모두 GAF입니다. TA: Kingdoms는 같은 컨테이너를 .taf 확장자로 팔레트 방식 애니메이션(팔레트는 부속 파일에서 가져옴)에 재사용합니다. TA:K에는 인덱스 대신 16비트 ARGB 픽셀을 저장하는 트루컬러 .taf 변형도 있는데, 이것은 별도 페이지 TAF / TSF에서 다룹니다.

kbot gaf list   anims/cursors.gaf                                      # sequences, frame counts, loop flag
kbot gaf export anims/cursors.gaf --format gif --sequence 0 --target cursor.gif
kbot gaf dump   anims/cursors.gaf --target ./cursors                   # one PNG per frame

import "github.com/coreprime/kbot/formats/gaf"

r, _ := gaf.LoadFromFile("anims/cursors.gaf")
defer r.Close()
sequences, _ := r.ReadSequences()
for _, seq := range sequences {
    fmt.Println(seq.Name, len(seq.Frames))
}

한눈에 보기#

┌─ Header (12B) ─┐
│ ver  N  pad    │
└────────┬───────┘
         ▼
┌─ Sequence offset table ─┐  N × uint32 absolute offsets
└───┬─────────────────────┘
    ▼
┌─ SequenceHeader (40B) ─┐
│ frameCount, loop word, │
│ +4 word, name[32]      │
└─────────┬──────────────┘
          ▼
┌─ FrameListItem (8B) × frameCount ─┐  ptr + tick duration
└───┬───────────────────────────────┘
    ▼
┌─ FrameInfo (24B) ─┐
│ size, origin,     │
│ transparency,     │
│ compressed?,      │
│ layers, +11 byte  │
│ ptrPixelData      │
└─────┬─────────────┘
      ▼
┌─ Pixel data: raw or run-encoded ─┐
└──────────────────────────────────┘

GAF는 시퀀스를 늘어놓은 단순한 배열이고, 각 시퀀스는 프레임의 배열이며, 각 프레임은 원점과 (선택적으로) RLE 방식의 투명 런을 가진 너비 × 높이의 팔레트 인덱스 비트맵입니다. 프레임은 "서브프레임"을 가질 수 있어서, 논리적인 애니메이션 한 단계를 여러 겹의 레이어를 합성해 만들 수 있습니다.

헤더(12바이트)#

typedef struct {
    uint32 Version;        // 0x00010100 (or 0 for a handful of stock GAFs)
    uint32 SequenceCount;  // Number of animations in the file
    uint32 Unknown1;       // Always 0
} GAFHeader;

시퀀스(40바이트)#

typedef struct {
    uint16 FrameCount;
    uint16 LoopFlags;      // +2: low byte non-zero = the sequence loops
    uint32 Unknown4;       // +4: not used by the game; stock files store 0
    char   Name[32];       // NUL-padded, case-preserved
} GAFSequence;

게임은 LoopFlags의 하위 바이트가 설정되어 있으면 시퀀스를 반복하고, 0이면 한 번만 재생합니다(그 뒤 마지막 프레임에서 멈춤). Cavedog의 기본 시퀀스는 모두 1을 저장합니다. kbot은 파일을 다시 쓸 때 두 워드를 모두 유지하며, kbot gaf build는 sequence.csv가 없는 시퀀스에 기본값 1을 줍니다.

그 뒤에 FrameCount × FrameListItem이 이어집니다.

typedef struct {
    uint32 PtrFrameInfo;   // → FrameInfo
    uint32 Duration;       // Game ticks (30 ticks = 1 second); low 16 bits used
} FrameListItem;

게임은 Duration의 하위 16비트만 읽고, 30 Hz 애니메이션 시계로 max(Duration, 1)틱 동안 프레임을 보여 줍니다.

시퀀스 이름은 중요합니다 — 게임은 애니메이션을 이름으로 찾습니다(예: UnitInfo는 corpyro.gaf 스크립트의 corpyro_smoke를 참조합니다). 비교할 때는 대소문자를 구분하지 않는 ASCII로 취급하세요.

프레임(24바이트 정보 + 페이로드)#

typedef struct {
    uint16 Width;
    uint16 Height;
    int16  OriginX;            // Render anchor, may be negative
    int16  OriginY;
    uint8  TransparencyIndex;  // Key: transparent in raw frames
    uint8  Compressed;         // 0 = raw bitmap, non-zero = run-encoded
    uint8  LayerCount;         // +10: 0 = simple frame, >0 = composite of layers
    uint8  Blend;              // +11: set on a layer = drawn translucently
    uint32 Unknown2;           // +12: editor scratch, not used by the game
    uint32 PtrFrameData;       // → pixel bytes OR layer pointer table
    uint32 Unknown3;           // Always 0
} FrameInfo;

OriginX / OriginY는 프레임을 월드에 그려 넣을 때 쓰는 기준점을 나타냅니다. 폭발 스프라이트라면 원점은 보통 폭발의 중심이고, 커서라면 핫스팟 픽셀입니다.

레이어 프레임#

LayerCount > 0이면 PtrFrameData는 픽셀 데이터가 아니라 **중첩된 FrameInfo**를 가리키는 LayerCount × uint32 포인터 배열입니다. 각 레이어는 배열 순서대로(뒤에서 앞으로) 그려지며, 그 핫스팟이 바깥 프레임의 핫스팟에 맞춰집니다. +11 바이트가 설정된 레이어는 그대로 복사되는 대신 반투명 테이블을 거쳐 그려집니다(이를 설정한 기본 파일은 없음). +10 바이트와 +11 바이트는 별개의 필드입니다. 둘을 16비트 개수 하나로 읽으면 +11 바이트에 값이 있을 때 그것이 레이어 256개로 둔갑합니다.

픽셀 데이터#

TransparencyIndex는 파일 전체가 아니라 프레임별 값입니다 — 예를 들어 커서 GAF는 어떤 프레임에서는 인덱스 9(시스템 분홍색)를, 다른 프레임에서는 인덱스 0을 씁니다.

비압축(Compressed == 0)#

Width × Height바이트를 위에서 아래로, 왼쪽에서 오른쪽 순서로 저장합니다. 게임은 TransparencyIndex와 같은 픽셀을 제외한 모든 픽셀을 그립니다. 유닛 텍스처(textures/*.gaf)와 시야 마스크(anims/vismasks.gaf)는 평범한 픽셀 배열로 읽히므로 그 프레임은 반드시 비압축이어야 하며, 실제로 그곳의 기본 프레임은 모두 비압축입니다.

압축(Compressed != 0) — TA 런 렝스 인코딩#

픽셀 데이터는 서로 독립된 Height개의 행으로 이루어집니다. 각 행은 uint16 lineLength로 시작하고, 그 뒤에 정확히 lineLength바이트의 런 렝스 인코딩된 바이트 스트림이 이어집니다. 그 스트림 안에서 각 청크는 1바이트 마스크로 시작하며, 마스크의 하위 2비트가 청크 종류를 정합니다.

따라서 청크당 최대 런 길이는 투명 픽셀 127개, 반복 픽셀 64개, 리터럴 픽셀 64개입니다. 건너뛴 픽셀만 투명합니다: 반복 픽셀이나 리터럴 픽셀은 값이 TransparencyIndex와 같아도 그려지며, 팔레트 인덱스 0은 평범한 불투명 검정입니다. 인코딩된 행이 Width보다 먼저 끝나면 kbot은 나머지를 투명 픽셀로 채우고 이를 보고합니다. 게임은 그 뒤의 바이트까지 계속 읽어 버립니다. 레이어는 바깥 프레임보다 작을 수 있으며 자체 OriginX/Y로 위치가 정해집니다.

참고: formats/gaf/gaf.go readCompressed 및 formats/gaf/writer.go compressRow.

TA: Kingdoms — 팔레트 결정#

TA: Kingdoms는 TA와 같은 .gaf(가끔 .taf) 컨테이너를 쓰지만, 팔레트는 에셋별 부속 파일에서 가져옵니다. 정식판 TAK 설치본은 문서화된 세 가지 관례를 우선순위 순으로 따릅니다.

1. .gaf 옆에 있는 같은 이름의 .pcx. UI/애니메이션 에셋은 원하는 팔레트를 PCX의 PLTE 청크로 담은 1×1 PCX 파일과 함께 배포됩니다. anims/actionbuttons.gaf는 anims/actionbuttons.pcx의 팔레트로 렌더링됩니다. TAK의 anims/*.gaf 파일 중 약 38%가 이런 부속 파일을 갖고 있습니다.

2. palettes/에 있는 같은 기본 이름의 .pal. 드뭅니다. Cavedog이 1024바이트 원시 팔레트를 내보낸 몇몇 기본 에셋이 해당됩니다.

3. 파일 이름 접두사에 따른 진영별 팔레트. 유닛과 지형지물 GAF는 세 글자 진영 접두사로 이름이 붙어 있으며, 그에 맞는 진영 팔레트를 씁니다.

   접두사	진영	팔레트 파일
   ara*	Aramon	palettes/aramon.pcx
   tar*	Taros	palettes/taros.pcx
   ver*	Veruna	palettes/veruna.pcx
   zon*	Zhon	palettes/zhon.pcx
   aid*	Aiden(Iron Plague)	palettes/aiden.pcx
   cre*	Creon(Iron Plague)	palettes/creon.pcx

이 중 어느 것도 찾지 못하면 리졸버는 palettes/palette.pal을, 그것도 없으면 내장 TA 팔레트를 씁니다. 정식판 TAK에서 이 둘은 서로 같고 TA의 팔레트와도 바이트 단위로 같으므로, 진영 접두사에 맞지 않는 유닛/지형지물 GAF는 명시적으로 지정하지 않으면 색이 틀리게 나옵니다.

kbot의 리졸버#

internal/palettepick이 위의 단계를 구현합니다. GAF를 렌더링하는 모든 진입점이 이를 거칩니다.

• 웹 탐색기. /png/…와 /apng/… 경로는 기본적으로 자동 감지합니다. GAF 뷰어는 리졸버가 찾은 모든 후보와 auto 항목을 나열하는 팔레트 드롭다운을 보여 줍니다. 특정 팔레트를 강제하려면 ?palette=<vfs-path>를 넘기세요(드롭다운이 대신 해 줍니다).
• kbot gaf export / kbot gaf dump. 바꾸려면 --palette <path.pcx|path.pal>을 넘기세요. 그렇지 않으면 내장 TA 팔레트를 씁니다(CLI는 kbot mount로 감싸지 않는 한 VFS 컨텍스트가 없으므로 VFS 리졸버를 실행하지 않습니다).
• MCP gaf_export 도구. 선택적인 palette 인수(설정된 game-data 폴더 안의 경로)를 받으며, 생략하면 리졸버 전체를 실행합니다.

TA GAF를 TA: Kingdoms로 옮기기#

TA와 TAK의 GAF 바이트 구조는 같고 팔레트 출처만 다릅니다. 기존 TA .gaf를 옮기려면:

1. TA 팔레트를 담은 1×1 팔레트 방식 PCX를 만듭니다.
2. 그것을 GAF 옆에 같은 기본 이름으로 저장합니다(예: MyGaf.gaf + MyGaf.pcx).

이것만으로 TAK가 원래 TA 색상으로 렌더링합니다.

TA: Kingdoms — 투명도 특이점#

TAK의 많은 텍스처 아틀라스 GAF(textures/*.gaf 전부와 anims/*.gaf의 상당수)에는 메타데이터의 TransparencyIndex가 실제 픽셀 데이터에 한 번도 나오지 않는 어떤 상수(보통 9)로 되어 있는 비압축 프레임이 있습니다. 정작 아티스트는 "투명" 테두리를 다른 팔레트 인덱스(흔히 5)로 채웠습니다. 메타데이터를 글자 그대로 읽으면, TA의 렌더러라면 투명했을 자리에 불투명한 색 배경이 렌더링됩니다.

TA의 렌더러는 절대 추측하지 않습니다. 비압축 프레임에는 저장된 키를, 압축 프레임에는 건너뛰기 명령을 씁니다. TAK 아틀라스를 위해 kbot은 선택해서 켜는 모서리 검출 휴리스틱(TransparencyModeHeuristic, kbot-io의 formats/gaf에 있는 EffectiveTransparencyIndex 참고)을 제공하며, 이는 비압축 프레임에만 적용됩니다.

1. TransparencyIndex가 픽셀 버퍼 어딘가에 있으면 메타데이터를 믿습니다.
2. 그렇지 않으면 네 모서리를 샘플링합니다. 네 값이 모두 같으면 그 값을 실질적인 투명 인덱스로 씁니다. 아티스트가 균일한 테두리를 그린 TAK 비압축 프레임은 이 단계에서 제대로 처리됩니다.
3. 그것도 아니면 디스크상의 TransparencyIndex를 그대로 씁니다. 그래서 dungwormB1처럼 모서리까지 유닛 픽셀로 꽉 찬 텍스처도 제대로 렌더링됩니다. 이런 경우 자동 감지가 값을 덮어쓰지 않는 것이 맞습니다.

압축 프레임과 합성 프레임은 항상 건너뛴 픽셀을 씁니다. 디스크상의 바이트는 절대 덮어쓰지 않으므로 왕복 변환 라이터는 원래 값을 봅니다. 균일한 테두리가 있는 완전히 불투명한 TA 프레임은 이 휴리스틱을 쓰면 테두리를 잃게 되므로, TA 렌더링에서는 절대 쓰지 않습니다.

렌더링할 때 투명도 바꾸기#

gaf.RenderOptions는 다음 모드를 제공합니다.

내보낸 이미지의 팔레트 항목은 투명 슬롯 하나(보통 프레임의 키)를 빼고 모두 불투명합니다. 프레임이 키와 같은 값의 픽셀을 그리는 경우(또는 한 애니메이션의 프레임들이 서로의 키를 색으로 쓰는 경우)에는 그려진 픽셀이 쓰지 않는 인덱스를 대신 투명 슬롯으로 삼으므로, 이미지에 모든 팔레트 인덱스가 그대로 남습니다.

에셋 탐색기의 GAF 뷰어는 팔레트 선택기 옆에 Default / Game rule / Corner guess / None 드롭다운을 제공하며, 선택한 값을 모든 PNG/GIF/APNG 요청에 ?transparency=game|heuristic|none|<N>으로 넘깁니다. 기본값은 TA에서는 게임의 규칙, TA: Kingdoms 설치본에서는 모서리 추측입니다. 캐시 키에 투명도 태그가 포함되므로, 모드를 바꿔도 오래된 렌더링 결과가 나오지 않습니다.

MCP gaf_export 도구도 같은 기본값을 따릅니다. 기본은 게임의 규칙이지만, TA: Kingdoms로 등록된 game-data 폴더(takingdoms kbot 컨텍스트)에서는 모서리 추측을 쓰며, 결과에 사용한 모드를 표시합니다. kbot gaf export는 게임 컨텍스트 없이 일반 파일을 읽으므로 기본값이 게임의 규칙입니다. TA: Kingdoms 아틀라스에는 --transparency heuristic을 넘기세요. kbot gaf build가 이미지에서 저장된 키를 다시 읽어 오기 때문에 kbot gaf dump는 항상 게임의 규칙을 씁니다.

실제 예제 — cursors.gaf#

$ kbot gaf list anims/cursors.gaf
GAF: 22 sequence(s), version 0x00010100

#   Name             Frames  Loops  Duration (ticks)  Duration (sec)
─   ────             ──────  ─────  ────────────────  ──────────────
0   cursormove       8       yes    64                2.13
1   cursorgrn        1       yes    10                0.33
2   cursorselect     2       yes    12                0.40
...

전형적인 cursormove 프레임:

Width:       32
Height:      32
OriginX:     16        ← hotspot in the middle of the cursor
OriginY:     16
Transparency: 0        ← this frame's key (compressed, so only skips are transparent)
Compressed:  1         ← run-encoded
LayerCount:  0         ← flat (no sub-frames)

GAF 만들기#

kbot gaf dump는 kbot gaf build가 다시 읽을 수 있는 디렉터리 구조를 씁니다.

cursors/
├── cursormove/
│   ├── sequence.csv    ← index,name,loop_flags,unknown4
│   ├── frames.csv      ← frame,width,height,origin_x,origin_y,transparency,
│   │                     duration_ticks,duration_sec,storage,blend
│   ├── animated.png    ← preview only; not read back
│   ├── 0.png
│   ├── 1.png
│   └── ...
└── ...

kbot gaf dump  anims/cursors.gaf --target ./cursors
# edit some PNGs / tweak frames.csv or sequence.csv
kbot gaf build ./cursors --target ./cursors-rebuilt.gaf
kbot gaf roundtrip anims/                     # check dump/build keeps what the game reads

프레임 이미지는 게임의 규칙으로 그린 인덱스 PNG(--format gif를 주면 GIF)이므로, 모든 픽셀이 팔레트 인덱스를 유지하고 투명 픽셀만 따로 표시됩니다. build 단계는 그 인덱스를 그대로 다시 복사하고 투명 픽셀을 프레임의 키로 바꿉니다. RGBA 이미지는 대신 키를 피해 가장 가까운 팔레트 색상으로 맞춥니다.

• sequence.csv는 시퀀스 순서, 정확한 이름, 반복 워드, +4 워드를 복원합니다. 이 파일이 없으면 폴더 이름이 시퀀스 이름이 되고, 모든 기본 시퀀스처럼 반복 재생됩니다.
• storage(raw 또는 compressed)와 blend(+11 바이트)는 각 프레임의 헤더를 복원합니다. storage 값이 없는 프레임은 압축되지만, textures/*.gaf나 anims/vismasks.gaf에 쓰이는 프레임은 게임이 평범한 픽셀 배열로 읽으므로 모두 비압축입니다. --storage raw|compressed는 두 경우 모두를 덮어씁니다.
• 합성(레이어) 프레임은 하나로 합친 이미지로 덤프되고 단순 프레임으로 다시 만들어집니다. kbot gaf roundtrip이 그 개수를 보고합니다.
• 픽셀이 없는 프레임(너비나 높이가 0)에는 이미지가 없으며, frames.csv의 행만으로 다시 만들어집니다.
• frames.csv도 sequence.csv도 없는 하위 폴더는 경고와 함께 건너뜁니다. 그 밖에 만들 수 없는 하위 폴더(이미지가 없거나 읽을 수 없음, CSV 값이 잘못됨)가 있으면 build가 중단되므로, 시퀀스가 아무 말 없이 빠지는 일은 없습니다.

주의할 점#

• 일부 시퀀스는 프레임 길이가 0인 채로 출시되었습니다. 게임은 그런 프레임을 길이 1처럼 한 틱 동안 보여 줍니다. 기본값으로 "고치지" 마세요.
• 압축된 픽셀 행은 Width보다 짧을 수 있습니다. 게임은 다음 바이트들을 명령으로 계속 읽어 버리고, kbot은 행을 투명 픽셀로 채우고 이를 보고합니다. 그런 행이 있는 기본 파일은 없습니다.
• 레이어 원점은 핫스팟입니다: 각 레이어는 그 원점이 바깥 프레임의 원점에 오도록 배치됩니다.
• TA: Kingdoms의 .taf는 두 종류입니다. kbot은 팔레트 방식 .taf를 일반 GAF로 읽지만, TA:K에는 트루컬러 .taf 파일(16비트 ARGB 픽셀, 팔레트 없음)도 있습니다. 둘을 구별하려면 프레임 형식 바이트를 확인하고, 트루컬러 변형은 TAF / TSF를 참고하세요.
• anims/terrain.gaf와 anims/vismasks.gaf는 Version == 0입니다. 게임은 버전 워드를 무시합니다.
• 시퀀스당 프레임 수에는 상한이 없습니다 — cursorteleport는 프레임이 46개입니다. 버퍼 크기를 정할 때 고정된 상한을 가정하지 마세요.

일반적인 크기#

레퍼런스 카탈로그의 실제 예#

TA 설치본의 눈여겨볼 GAF들입니다 — kbot hpi extract로 꺼낸 다음 kbot gaf list / kbot gaf export로 살펴보세요.

• anims/cursors.gaf — 시퀀스 22개, 각각 UI 커서 애니메이션입니다. 가장 작은 시퀀스(cursorgrn, cursorred)는 프레임 하나이고, 가장 큰 것(cursorteleport)은 460틱에 걸친 46프레임입니다. 위의 실제 예제 절에서 다뤘습니다.
• anims/textures.gaf — 약 12 MB, 모든 3DO 모델의 OffsetToTextureName 문자열이 참조하는 마스터 타일 시트입니다. kbot gaf list anims/textures.gaf | head로 훑어보세요.
• anims/explosions.gaf 계열 — 전형적인 효과 GAF: lasersht.gaf, acid.gaf, bigexpls.gaf — 각각 이름 붙은 폭발 시퀀스를 여러 개 담고 있습니다.
• anims/armcom.gaf / corcom.gaf — 진영별 커맨더 장치(선택 원, 건설 레이저).
• anims/terrain.gaf + anims/vismasks.gaf — 헤더에 Version == 0이 있는 유일한 기본 GAF입니다(파서를 짤 때 알아 둘 만합니다).

함께 보기#

• TAF / TSF — 같은 컨테이너를 바탕으로 한 TA: Kingdoms의 트루컬러 .taf 변형과 그 편집 가능한 텍스트 형식.
• PAL — GAF 프레임을 렌더링하는 데 필요한 색상표.
• PCX — TA:K가 팔레트 방식 .taf에 팔레트를 공급하는 방식.
• 3DO — "스프라이트"가 실제로는 텍스처를 입힌 3D 모델인 경우(폭발은 대부분 GAF, 투사체는 대부분 3DO + GAF 포구 섬광).
• 용어집 — sub-frame, origin, tick.