Level 2: SDK Integration (Leaderboard + Clips)

🎯 목표

3sec-score SDK를 게임에 연동해서:

게임오버 시 점수가 리더보드에 올라가고
플레이 영상이 자동으로 녹화되어 Play Feed에 공유됩니다

📋 준비물

Level 0~1에서 만든 게임 파일 (index.html)
게임이 호스팅된 URL (GitHub Pages, Vercel 등)

💡 로컬 파일에서도 테스트할 수 있지만, 실제 점수 제출은 호스팅 후 가능합니다.

단계별 가이드

Step 1. SDK 스크립트 추가

index.html의 <head> 또는 <body> 끝에 SDK를 추가합니다:

<script src="https://www.3secgames.app/sdk/3sec-score.js"></script>

Level 0 프롬프트에 이미 포함되어 있습니다. 없다면 추가하세요.

Step 2. 게임오버 시 점수 제출

게임오버 함수에서 submitScore를 호출합니다:

// 게임오버 처리 함수 안에서:
async function gameOver() {
  // ... 게임오버 UI 표시 ...

  try {
    const result = await submitScore('your-game-id', score);
    console.log('Personal best:', result.personalBest);
  } catch (err) {
    if (err.message === 'cooldown') {
      console.log('잠시 후 다시 시도해주세요');
    }
  }
}

'your-game-id'는 나중에 게임 제출 후 발급받는 실제 ID로 교체합니다.

Step 3. 플레이 클립 자동 녹화

SDK에 내장된 녹화 기능을 활성화합니다:

// 게임 시작 시 (canvas가 준비된 후):
function startGame() {
  startRecording('your-game-id');
  // ... 게임 루프 시작 ...
}

startRecording()을 호출하면:

canvas를 30fps로 녹화 시작
최근 30초를 순환 버퍼에 유지
submitScore() 호출 시 자동으로 클립 업로드

💡 녹화가 실패해도 게임에는 전혀 영향이 없습니다. Canvas 캡처를 지원하지 않는 환경에서는 조용히 무시됩니다.

Step 4. 하이라이트 클립 (선택사항)

더 짧고 인상적인 하이라이트 클립을 원한다면 3sec-clip SDK도 추가할 수 있습니다:

<script src="https://www.3secgames.app/sdk/3sec-clip.js"></script>

// 게임 시작 시:
initClip('your-game-id');

// 점수가 변할 때마다:
function updateScore(newScore) {
  score = newScore;
  reportScore(score); // 10% 이상 증가 시 자동 캡처
}

// 게임오버 시:
async function gameOver() {
  await uploadHighlight(); // 가장 좋은 하이라이트 업로드
  await submitScore('your-game-id', score);
}

두 SDK는 동시에 사용 가능합니다:

3sec-score.js → 전체 30초 클립 + 리더보드
3sec-clip.js → 하이라이트 10초 클립

Step 5. 플레이어 닉네임 설정

플레이어가 닉네임을 설정하면 리더보드에 이름이 표시됩니다:

// 게임 시작 전 닉네임 입력 받기:
const name = prompt('닉네임을 입력하세요 (최대 8자)');
if (name) setPlayerName(name);

// 현재 닉네임 가져오기:
const currentName = getPlayerName(); // '' 이면 미설정

Step 6. 호스팅 & 테스트

GitHub Pages: 리포에 index.html 푸시 → Settings → Pages → Deploy
Vercel: vercel CLI로 배포 또는 GitHub 연결
배포된 URL에서 게임 플레이 → 개발자 도구 Network 탭에서 /api/leaderboard POST 확인

✅ 체크포인트

[ ] 3sec-score.js 스크립트가 로드된다
[ ] 게임오버 시 submitScore() 호출이 성공한다 (Network 탭 확인)
[ ] startRecording()으로 녹화가 시작된다
[ ] 게임오버 후 클립이 자동 업로드된다
[ ] (선택) 3sec-clip.js로 하이라이트 캡처가 동작한다
[ ] 호스팅된 URL에서 모든 기능이 정상 동작한다

🐛 잘 안 될 때

"submitScore가 정의되지 않았어요"

<script> 태그가 submitScore() 호출보다 먼저 로드되었는지 확인
스크립트 태그에 type="module" 사용 시: SDK를 import로 가져와야 합니다

"점수가 제출 안 돼요 (CORS 에러)"

로컬 파일 (file://)에서는 CORS 제한으로 API 호출 실패
해결: 로컬 서버로 실행 (npx serve . 또는 VS Code Live Server)

"녹화 클립이 업로드 안 돼요"

startRecording()을 canvas가 생성된 후에 호출했는지 확인
브라우저가 canvas.captureStream()을 지원하는지 확인 (Chrome/Edge 권장)
클립 크기가 10MB 초과 시 자동 생략됩니다

"429 에러 (cooldown)"

점수 제출은 30초 쿨다운이 있습니다
테스트 시 30초 간격으로 제출하세요

🤖 AI 모델별 접근법

무료로 시작

Gemini 3.1 Pro — SDK 스크립트 태그 삽입과 async/await 패턴 생성에 안정적. 무료 티어로 충분.
DeepSeek-V3.2 — API 연동 코드 생성 능력 우수. CORS 이슈 해결 방법도 잘 안내.

상용 모델

Claude Opus 4.6 — 3sec-score SDK 문서를 컨텍스트에 넣으면 완벽한 연동 코드 생성.
GPT-5.4 — 에러 핸들링(cooldown, 네트워크 실패)까지 포함한 견고한 코드.

로컬 실행

Ollama + Qwen2.5-Coder 32B — SDK 연동은 비교적 단순해서 로컬 모델로도 충분히 가능.

IDE 통합

Cursor — SDK 스크립트와 기존 게임 코드를 동시에 열어 참조하며 작업 가능.

🎉 축하합니다!

이제 게임이 3secgames.app 생태계와 연결되었습니다! 🏆

플레이어들이 리더보드에서 경쟁하고, 플레이 클립이 Feed에 공유됩니다.

다음 레벨에서는 점수 밸런싱과 난이도 커브를 설계합니다.

Level 3: 밸런싱과 난이도 설계 →

SDK 연동 (리더보드 + 클립)