Files
joke-app/docs/06-lobby-rooms.md

16 KiB
Raw Blame History

06. 로비와 방

1. 목표

  • 방 만들기: 첫 화면에서 게임 카드 누르기 → "방 만들기" 두 번이면 대기실, 코드와 링크가 바로 보인다.
  • 방 참여: 링크를 누르면 바로 대기실(처음이면 닉네임 한 칸). 코드를 받았으면 첫 화면 "코드로 참여"에 숫자 6개.
  • 글을 몰라도 쓸 수 있게 큰 아이콘 + 짧은 글자.

2. 화면과 주소

주소 화면
/ 홈: 위쪽에 큰 버튼 두 개 [방 만들기] [코드로 참여], 그 아래 "진행 중인 게임으로 돌아가기"(있을 때만), 그 아래 게임 카드 목록
/g/:gameId 게임 소개: 한 줄 설명, 인원, 시간, 난이도, [방 만들기] [컴퓨터와 연습하기] [규칙 보기]
/r/:code 방(대기실 ↔ 게임 화면 ↔ 결과 화면이 같은 주소에서 전환)
/j 코드 입력 전용 화면(숫자 키패드)
/me 계정
/rules/:gameId 규칙 설명(그림 포함)

초대 링크는 https://<도메인>/r/123456. 짧고 읽기 쉬워서 말로 불러 줘도 된다.

3. 방 코드

  • 6자리 숫자(000000 제외, 같은 숫자 6개·연속 숫자 제외). 숫자만 쓰는 이유: 어르신·어린이가 키패드로 입력하기 가장 쉽고, 말로 전달하기 쉽다.
  • 화면에는 123 456처럼 3자리씩 띄어 보여 준다. 입력은 띄어쓰기·하이픈 무시.
  • 사용 중인 코드와 겹치지 않게 무작위 발급. 방이 끝나고 24시간 동안은 같은 코드 재사용 금지(옛 링크로 엉뚱한 방에 들어가는 것 방지).
  • 코드 입력 화면: 6칸 큰 숫자 칸, 휴대폰 숫자 키패드(inputmode="numeric"), 6자리가 채워지면 자동으로 입장 시도. 클립보드에 6자리 숫자나 초대 링크가 있으면 "붙여넣기" 버튼을 크게 표시.

4. 방 만들기

  1. 게임 선택(홈 카드 또는 홈의 [방 만들기] → 게임 고르기 화면).
  2. 바로 대기실 생성. 모든 옵션은 기본값으로 이미 정해져 있다(인원은 게임 기본 인원, 공개 여부는 "친구만(비공개)").
  3. 대기실에서 방장이 바꿀 수 있는 것: 게임 모드/옵션(시간 제한 포함 — 게임마다 다름), 최대 인원(게임의 최소~최대 범위 안), 관전 허용, 채팅 허용. 바꾸는 즉시 서버에 저장된다(저장 버튼 없음). 그래서 [게임 시작]은 언제나 화면에 보이는 설정으로 시작한다.
    • 방은 모두 친구만(비공개)이다. 아는 사람끼리만 하므로 공개 설정은 화면에 두지 않는다.
  4. 옵션은 "기본 설정" 몇 개만 보이고 나머지는 "자세한 설정" 접기 안에 둔다.

5. 대기실 화면 (PC는 두 칸 배치 — 07-ui-ux.md 3.4. 아래는 내용 순서이며 좁은 화면에서는 이 순서로 한 칸에 쌓인다)

  1. 초대 카드(가장 눈에 띄게, 빈자리가 있을 때만 — 다 차면 숨기고 방 막대의 🔗 링크 복사만 남긴다): 큰 글씨 코드 123 456
    • [링크 복사] [공유하기](모바일: 공유 시트 → 카카오톡 등. 공유가 안 되는 PC는 [초대글 복사]) 두 개만. 코드는 크게 보이므로 따로 복사 버튼을 두지 않는다. QR(같은 공간의 가족이 폰으로 찍어서 입장)은 빈자리 칸 "+ 빈자리 · 📷 QR로 초대"를 누르면 뜬다.
    • 복사하면 버튼이 1.5초간 "복사했어요 ✓"로 바뀜 + 진동(지원 기기).
    • 공유 문구: "OO님이 오목 방에 초대했어요! 코드 123 456 · https://<도메인>/r/123456"
  2. 자리 목록: 게임 인원만큼 자리 칸. 각 칸: 프로필, 닉네임, 방장 왕관, 준비 체크, 연결 상태 점(초록/노랑/회색). 빈자리는 점선 "+ 빈자리 · 📷 QR로 초대"(누르면 QR. 아직 자리가 없는 사람에게는 "+ 여기 앉기").
    • 닉네임(자리, 관전자 목록, 결과 화면)을 누르면 기록 카드가 뜬다: 이 게임의 판·승·패·무·승률, 이 방 전적, 전체 게임 합계. 패 = 판 - 승 - 무(1등이 아니면 패). 컴퓨터는 누를 수 없다. GET /api/users/:id/stats(로그인 필요).
    • 게스트에게는 [게임 시작]/[준비하기] 아래에 한 줄로 "⚠️ 게스트 기록은 하루 동안 안 들어오면 지워져요."를 보인다(연습 방 제외).
    • 규칙 설명은 대기실에 펼쳐 두지 않는다. 방 막대의 [📖 규칙]으로 본다.
  3. 게임 설정: 요약 "오목 · 렌주룰 · 한 수 30초" + 방장은 [설정 바꾸기], 나머지는 [설정 보기](PC는 카드 안에 바로 펼침). 참여자도 방장과 같은 설정 화면(자세한 설정 포함)을 보지만 모든 버튼이 잠겨 있어 바꿀 수 없다. "👑 설정은 방장만 바꿀 수 있어요" 안내. 방장이 바꾸면 바로 따라 바뀐다(2026-10-11). 서버도 방장 외 config를 거절한다.
  4. 아래 고정 버튼(엄지 닿는 곳):
    • 방장: [게임 시작] — 최소 인원이 안 되면 비활성 + "1명 더 필요해요" 안내. 모두 준비가 아니어도 시작 가능하되 "준비 안 된 사람이 있어요. 시작할까요?" 확인.
    • 나머지: [준비하기] / [준비 취소].
  5. 채팅(접을 수 있음), 관전자 수.

방장 기능: 내보내기, 방장 넘기기, 자리 순서 섞기(선 정하기), 게임 바꾸기(같은 방 유지 — 친구들끼리 여러 게임 이어서 하기). 방장이 나가면 가장 먼저 들어온 사람이 방장.

6. 링크로 들어오기

  1. /r/123456 접속.
  2. 로그인 안 됨 → 같은 화면 위에 작은 창: 방 정보("오목 · 방장 OO · 1/2명") + 닉네임 칸(추천 이름 채워짐) + [이 이름으로 입장] + 작게 [디스코드로 로그인].
  3. 입장 → 빈자리가 있으면 자동으로 자리에 앉는다. 없으면 관전자로 들어가고 "자리가 나면 앉을 수 있어요".
  4. 방이 없거나 끝났으면: "이 방은 끝났어요" + [같은 게임 새 방 만들기] [홈으로].

7. 빠른 시작 (화면에서 뺌)

  • 아는 사람끼리만 하므로 [빠른 시작](모르는 사람 기다리기)은 화면에서 뺐다. 서버의 POST /api/quick/:gameId는 남아 있지만 화면에서 부르지 않는다.

8. 게임 중

  • 위쪽 상태 줄: 지금 할 일 문장("내 차례예요" / "OO님 차례예요"), 남은 시간 링.
  • 방 막대(메뉴 버튼 없이 모두 밖에): [← 홈] 게임 이름(PC) · [🔗 방 코드 링크 복사] · 💬 채팅 · [📖 규칙] · [⚙️ 설정](글자 크기·소리, /me) · [🚪 나가기]. 휴대폰에서는 아이콘 아래 짧은 글자로 쌓아 한 줄(320px)에 들어가게 한다(버튼은 최대 6개).
  • 오류로 게임이 멈추면 방장에게만 상태 줄 바로 아래 [⏹ 게임 끝내기(무효)] 버튼이 나온다.
  • [🚪 나가기]와 [← 홈]은 같은 동작이다: 방에서 나가고 홈으로. 한 번 누르면 바로 나가고, 게임 중에 자리에 앉아 있을 때만 "게임 중에 나가면 기권으로 처리돼요" 확인을 한 번 더 묻는다.
  • 무르기 요청·무승부 제안·기권은 게임 화면 안의 버튼으로 한다(지원 게임).
  • 관전자는 [자리 나면 참가] 대기 가능(다음 판부터).

9. 게임 끝

  • 결과 화면: 순위, 점수, 핵심 장면 요약(예: "흑 5목 완성"), [한 판 더] [게임 바꾸기] [나가기].
  • 최종 점수(2026-10-11): 등수 줄마다 오른쪽에 그 판의 최종 점수를 진하게, 그 아래 "이 방에서 n승 / n판"을 작게 둔다. 문구는 게임이 GameResult.scoreText로 정한다. 점수 계열 요트·스플렌더·라스베가스·캐치마인드·달무티(누적 점수 방식)·원카드(색깔 카드)는 "n점", 고스톱·루미큐브는 "+n점/-n점", 마작 "35,000점(+25.0)", 오델로 "n점", 바둑 "n집 반"(중국식 "n점", 계가했을 때만), 장기 "기물 n점", 섯다·포커 "n칩", 부루마블 "총자산 nP", 윷놀이 "난 말 n개", 할리갈리 "카드 n장", 도블 "모은/남은/받은 카드 n장"·"벌점 n장". 점수가 없는 오목·체스·쿼리도·다빈치 코드·99·뱅·마피아·바퀴벌레 포커는 등수만 보인다.
  • [한 판 더]는 누른 사람을 그 방 대기실로 돌려보낸다(2026-10-11, 전에는 모두 눌러야 시작하는 투표라 한 명이 안 누르면 결과 창에서 계속 기다렸다). 자리에 앉은 사람이 누르면 "준비 완료"가 되어 방장이 누가 또 하고 싶은지 본다. 대기실에서 자리·컴퓨터·설정을 바꾼 뒤 방장이 [게임 시작]. 아직 결과 창을 보는 사람은 방장이 시작하면 새 판으로 넘어간다. 어느 판 뒤에 대기실로 왔는지는 탭마다 기억해서(sessionStorage) 새로고침해도 대기실에 남는다. 서버의 rematch 투표 메시지는 남아 있지만 화면에서는 쓰지 않는다.
  • 기록: 끝난 게임은 game_results에 저장, 방 안에서 "이번 방 전적"(예: OO 3승 2패) 표시.

10. 공개 방 목록 (화면에서 뺌)

  • 홈의 [지금 열린 방] 탭과 게임 상세의 "기다리는 방" 목록은 뺐다. 서버의 GET /api/public-rooms, GET /api/games/:gameId/rooms는 남아 있지만 화면에서 부르지 않는다.

11. 서버 방 모델

type RoomStatus = 'lobby' | 'playing' | 'finished' | 'paused' | 'broken';
interface Room {
  code: string;            // 6자리
  id: string;              // 내부 ULID
  hostId: UserId;
  gameId: GameId;
  options: unknown;        // 게임 optionsSchema로 검증된 값
  visibility: 'private' | 'public';
  maxPlayers: number;      // 게임 min~max 범위
  graceSec: number;        // 연결 끊김 유예(기본 60초). 턴 시간은 게임 옵션
  allowSpectators: boolean;
  chat: { enabled: boolean; filter: boolean };
  seats: Array<{ userId: UserId; ready: boolean } | null>;
  spectators: Set<UserId>;
  presence: Map<UserId, { connected: boolean; since: number; autoCount: number }>;
  status: RoomStatus;
  seq: number;
  game?: { state: unknown; rng: RngState; deadline: number | null; startedAt: number; seedHash: string };
  rematchVotes: Set<UserId>;
  sessionStats: Map<UserId, { wins: number; played: number }>;
  createdAt: number; lastActiveAt: number;
}
  • 한 사용자는 동시에 한 방에만 플레이어로 있을 수 있다(다른 방에 들어가면 이전 방 대기실 자리에서 빠짐. 이전 방이 게임 중이면 "진행 중인 게임이 있어요. 그래도 이동할까요?").
  • 제한: 서버 전체 방 2,000개, 사용자당 동시에 만든 방 3개.
  • 방 정리(1분마다): 접속이 하나도 없는 방 중 대기실은 10분, 끝난 방·멈춘 방은 30분 동안 활동이 없으면 닫는다. 컴퓨터가 있는 방(연습 방)은 마지막 사람이 나간 때부터 재서 대기실·끝난 방은 1분, 게임 중인 방은 30분 뒤 닫는다(사이트를 닫았으면 아래 규칙대로 1분). 마지막 사람이 [방 나가기]로 나가서 자리에 앉은 사람이 없으면(컴퓨터만 남았거나 아무도 들어오지 않은 방) 바로 닫는다.
  • 게임 중이거나 끝난 방(대기실 제외)에서 자리에 앉은 사람이 모두 사이트를 닫으면(서버와 연결된 창이 하나도 없으면) 마지막 사람이 닫은 때부터 1분 뒤 정리 때 닫는다. 진행 중인 게임은 무효 처리되고, 관전자는 셈하지 않고, 남아 있던 관전자도 방에서 내보낸다. 대기실은 초대받은 사람이 들어올 수 있으므로 위 규칙을 따른다. 자리가 있는 사람은 다른 화면에 있어도 서버 연결을 유지한다(새로 연 창에서도 /api/me의 activeRoom이 있으면 연결).
  • [← 홈]·[🚪 나가기]가 아닌 길(사이트 로고·위쪽 '홈' 링크, 규칙, 브라우저 뒤로 가기 등)로 방 화면을 벗어나면 클라이언트가 detach를 보낸다. 자리는 그대로이고 '접속 중'으로 남지만, 방 메시지를 받지 않고 방의 접속 수에서도 빠진다. 그 상태로 사이트를 닫으면 연결 끊김으로 처리한다.

12. 컴퓨터 상대 (혼자 연습)

  • 들어가는 곳: 게임 상세와 홈의 [🤖 컴퓨터와 연습하기]. 친구만 방이 열리고, 바로 시작할 수 있을 만큼 컴퓨터가 앉아 있다(예: 오목 1명, 마작 2명, 뱅 3명).
  • 대기실: 방장은 첫 빈자리의 [🤖 컴퓨터 넣기]로 넣고, 컴퓨터 자리의 [✕]로 뺀다(대기실에서만). 컴퓨터 이름은 "컴퓨터 1", "컴퓨터 2"…, 아바타는 🤖. 늘 준비 완료이고, 방장은 컴퓨터에게 넘어가지 않는다. 사람이 한 명은 앉아야 시작된다.
  • 컴퓨터가 앉은 방은 연습 방이다: 공개로 바꿀 수 없고, 공개 방 목록·빠른 시작에 나오지 않는다. 결과는 남지만 전적(user_stats)에는 넣지 않는다. 화면에 "연습 게임이에요. 기록에는 남지 않아요." 표시.
  • 컴퓨터가 할 수 있는 게임: 실시간·그림 게임(도블, 할리갈리, 그림 맞히기)을 뺀 전부(packages/shared/src/bots.ts의 BOT_GAMES). 마피아는 말하는 컴퓨터(2026-10-11, games/mafia.md §13), 연습 방은 6명으로 시작.
  • 움직임: 서버의 BotDriver(apps/server/src/rooms/bots.ts)가 게임이 컴퓨터를 기다릴 때(차례, 반응 창, 동시 선택, 다음 판 준비) 사람처럼 생각할 시간을 두고 한 수를 둔다(2026-10-11). 할 게 하나뿐이면 0.71.3초, 고를 게 있으면 1.63.9초(고를 수가 많을수록 길게), 가끔(12%) 13초 더 멈칫한다. 컴퓨터마다 빠르기가 달라서(botPace: 0.7배 빠른 편1.5배 신중한 편, 컴퓨터 id로 고정) 같은 판에서도 반응 속도가 다르다. 같은 컴퓨터가 이어서 두는 동작(요트 굴리기 → 고르기 등)은 절반 시간, 사람도 함께 반응할 수 있는 창(원카드 외치기 등)은 1.5초 더. 차례 시간이 있으면 남은 시간의 절반을 넘기지 않는다. 사람과 같은 행동 경로(검사·기록)를 거치고, 서버가 다시 켜져도 이어서 둔다.
  • 수 고르기: packages/games/src/<게임>/bot.ts. 자기 화면(view(state, 나))과 둘 수 있는 수만 보고 고르므로 남의 패를 볼 수 없다. 강하지 않지만 엉뚱하지 않게(오목은 4를 막고, 오셀로는 귀를 잡고, 카드 게임은 패 세기에 맞게).
  • 사람이 모두 나가면 게임은 무효로 끝난다.

12.1 사람처럼 노는 컴퓨터 (GPU 로컬 모델, 2026-10-11)

  • 수 고르기는 게임별 전략(자기 화면만 봄) 그대로다. 그 위에 GPU의 로컬 언어 모델(gemma3:4b, docs/11 §8)이 말과 심리전을 맡는다(apps/server/src/ai/).
  • 성격: 컴퓨터 id로 정해지는 5가지 — 도발형·허세형·차분형·수다형·소심형 — 와 말투(똑똑한 편 존댓말, 허술한 편 반말).
  • 보이는 행동: 수를 고르는 동안 "🤖 컴퓨터 1 생각 중…", 말할 때는 그 줄을 치는 만큼(글자 수 × 컴퓨터마다 다른 타자 속도, 0.9~6.5초) "💬 입력 중…"이 보인 뒤 채팅이 올라가고, 잠깐 뒤 수를 둔다(상태 줄과 채팅 칸, RoomView.botActivity).
  • 말하는 때: 자기 수와 함께 도발·심리전 한마디(성격별 14~38%, 방 전체 8초·컴퓨터마다 20초 간격), 사람의 수에 가끔 반응(12%), 사람이 이름을 부르거나 말을 걸면 대답(이름 부르면 꼭, 아니면 40%), 시작 인사, 끝나면 이긴 컴퓨터가 놀리거나 진 컴퓨터가 아쉬워함.
  • 심리전 판단: 바퀴벌레 포커에서 카드를 건넬 때 진짜를 말할지 블러핑할지를 모델이 정하고, 그걸 파는 한마디를 한다(실제 카드 이름이 들어간 말은 버림). 마피아는 컴퓨터가 계획한 대사(의심 지목·반박·반론 등)를 모델이 자기 말로 바꾼다. 모델에게 그 컴퓨터의 직업은 알려 주지 않고, "저 경찰이에요"·"나 마피아" 같은 직업 주장이 나오면 버리고 원래 대사를 쓴다.
  • 안전: 한 줄만, 40자 안팎, 한국어만(외국 문자·영어 단어·"AI"류 말 거름), 고운 말 필터·링크·전화번호 차단, 숨은 정보는 말하지 않게 지시.
  • 모델이 없거나 바쁘면 전처럼 조용히 둔다(게임은 모델을 기다리지 않는다).