README와 데모 GIF — 게임을 소개하는 법

게임이 완성되면 그다음 고민은 어떻게 소개하냐다.

텍스트만 있는 README는 게임을 설명하기 어렵다. 직접 실행해보지 않으면 어떤 느낌인지 알 수 없으니까. GIF 하나가 백 마디 설명보다 낫다.

GIF 캡처 — Playwright

게임플레이 영상을 Playwright로 캡처했다.

Playwright는 원래 브라우저 자동화·테스트 도구인데, 화면 녹화 기능도 있다. recordVideo 옵션을 주면 자동으로 .webm 파일이 생성된다.

const browser = await chromium.launch();
const context = await browser.newContext({
  recordVideo: {
    dir: './videos/',
    size: { width: 824, height: 515 },
  },
});

const page = await context.newPage();
await page.goto('http://localhost:8080');

// 게임 시작 — 엔터키
await page.keyboard.press('Enter');
await page.waitForTimeout(10000); // 10초 플레이

await context.close(); // 비디오 저장 트리거

context.close를 호출해야 영상이 실제로 저장된다. 이 부분을 빠뜨리면 파일이 생기지 않는다.

GIF 변환 — FFmpeg

Playwright가 만들어준 .webm을 FFmpeg으로 GIF로 변환했다.

# webm → GIF 변환
ffmpeg -i gameplay.webm \
  -vf "fps=10,scale=824:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  -loop 0 \
  gameplay.gif

palettegen + paletteuse 파이프라인이 핵심이다. GIF는 256색 제한이 있어서 단순 변환하면 색감이 무너진다. 팔레트를 따로 생성해서 적용하면 훨씬 자연스럽게 나온다.

fps=10은 파일 크기와 품질의 균형점이다. 24fps는 너무 크고, 5fps는 끊겨 보인다.

README 개편

GIF를 README에 넣으면서 전체 구성도 바꿨다.

전: 텍스트 위주 설명 + 스크린샷 1장

후:

# Lion Survival

![gameplay](assets/demo/gameplay.gif)

## 게임 방법
| 키 | 동작 |
|---|---|
| ↑ ↓ ← → | 이동 |
| ENTER | 게임 시작 |
| ESC | 일시정지 |

> 무기는 자동으로 공격합니다.

GIF가 맨 위에 오면 레포에 들어오는 사람이 즉시 어떤 게임인지 알 수 있다. 설명을 읽기 전에 이미 게임이 보이는 거다.

여러 번 다시 만든 이유

GIF 커밋이 9개나 된다.

처음엔 크기가 너무 작았고(400px), 그다음엔 프레임이 뭉개졌고, 고화질로 바꿨더니 파일이 너무 커졌다. 배지 추가하고, 프레임 스타일 바꾸고, 결국 824x515로 정착했다.

README도 코드처럼 반복적으로 다듬어야 한다.

게임 자체보다 소개하는 데 더 많은 시간을 쓴 것 같다.

근데 아무도 안 보는 게임은 만든 의미가 없으니까. 처음 1초에 눈길을 못 잡으면 그냥 지나친다.