Skip to content

About

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

똑똑 할로윈

픽셀 마을을 돌아다니며 친구 집 문을 두드리고 사탕을 주고받는 할로윈 게임. 코스튬, 호박 바구니, 노크 미니게임(사탕 낚시·유령 잡기·주문 외우기·사탕 받기 중 랜덤), 장난(trick), 뿅망치, 사탕을 건 1대1 대전, 방명록, 집 꾸미기, 아이템 상점, 지붕 그림, 채팅이 있다. 배경 음악과 효과음은 음원 파일 없이 브라우저에서 합성하고, 오른쪽 위 스피커 버튼을 눌러 연 소리 창에서 따로 켜고 끈다(기본은 음악 꺼짐·효과음 켜짐, 기기에만 저장).

Vercel 운영 주소와 담당 계정, main 머지 때만 자동 배포하는 흐름, 환경변수는 배포 및 운영 인계에 정리했다. 이 변경 배포 후 /로 접속할 수 있고 기존 /prototype/trick-or-treat.html 링크도 /로 연결된다.

PostHog로 체류 시간과 주요 플레이 행동을 분석할 수 있다. 공개 수집 키를 등록한 Vercel Production 빌드에서만 기본 활성화한다. 분석 설정·이벤트 목록·대시보드 가이드를 참고한다.

혼자 돌려 보기

prototype/trick-or-treat.html을 파일로 열면 연습 모드로 뜬다. 가짜 친구 두 집과 돌아다니는 봇(테스트친구)이 있고, 기록은 새로고침하면 사라진다. 계정 화면까지 보려면 아래 로컬 서버로 연다.

닉네임 계정과 로컬 개발

게임 HTML은 계속 prototype/trick-or-treat.html 하나를 원본으로 쓴다. Vercel 배포용 dist/index.html은 빌드할 때 원본으로 만들고, 분석을 켰을 때 client/의 PostHog 번들을 함께 연결한다. 인증 API와 Firebase 설정은 별도 서버 파일에 둔다.

Node.js 24와 Java 21이 필요하다. 패키지를 설치한 뒤 터미널 두 개에서 에뮬레이터와 게임 서버를 각각 실행한다. 로컬 서버는 항상 demo-trick-or-treat 에뮬레이터만 사용하며 실제 Firebase 프로젝트에는 연결하지 않는다.

npm install
npm run dev:emulators
npm run dev

브라우저에서 http://127.0.0.1:4173을 연다. Emulator Suite 화면은 http://127.0.0.1:4000에서 볼 수 있다. 배포 빌드는 npm run build로 만들고, npm test는 게임 회귀와 인증 정책 검사를 실행한다. npm run test:emulator는 인증·Firestore 에뮬레이터를 띄워 닉네임 경합, 잘못된 비밀번호, 기기 간 같은 UID, 보안 규칙을 검증한다.

가입할 때 서버가 고유 UID를 한 번 발급한다. 닉네임은 유니코드 NFKC 정규화 후 대소문자와 연속 공백을 무시해 중복을 막는다. 비밀번호는 8자 이상, UTF-8 기준 128바이트 이하이며 Firebase Auth에는 비밀번호를 보내지 않는다. 서버가 Firebase 커스텀 토큰으로 계정을 확인하고, Firestore에는 개별 salt를 적용한 scrypt 해시를 저장한다. 원문 비밀번호는 저장하지 않는다.

닉네임과 비밀번호만 사용하는 계정은 이메일 복구 기능이 없으며 비밀번호 초기화·복구 도구는 아직 구현하지 않았다. 닉네임은 로그인 ID로 사용하므로 옷장에서 변경할 수 없다. 브라우저의 Firebase 세션은 기기에 유지되어 같은 계정으로 재접속할 수 있다.

Firebase 로그인 뒤에는 여러 사람이 함께하는 마을로 들어간다. 캐릭터·호박·노크·사탕·장식·방명록·지붕 그림과 순위는 Firestore에 저장하고, 접속·위치·채팅·뿅망치는 Realtime Database로 공유한다. 이벤트 시작 전에는 연습 라운드이며 운영자가 시작하면 모두 사탕 10개로 새로 시작한다. 마을은 8채 단위로 나뉜다. 처음 분장한 순서대로 맨 뒤 마을에 들어가고, 길 위·아래 끝 표지판이나 '마을 지도' 창에서 다른 마을로 바로 갈 수 있다. 클라이언트는 지금 있는 마을의 플레이어·캐릭터 위치만 실시간으로 구독하고, 채팅과 접속자 목록(마을 번호만)은 모든 마을이 함께 받는다. 전체 순위는 순위 창을 열 때 한 번 읽는다. 운영자 UID 설정과 두 DB의 보안 규칙 배포가 필요하다.

같은 마을에서 가까이 선 두 사람은 사탕 1~10개를 걸어 대전을 신청할 수 있다. 상대가 수락하면 각자 사탕을 맡기고, 먼저 뿅망치 5대를 맞혀 상대를 기절시킨 사람이 전부 가져간다. 대전 중 접속이 끊기거나 시간이 끝나면 맡긴 사탕을 돌려준다.

Vercel 배포 환경 변수

.env.example을 참고해 Firebase Web 설정을 Vercel에 환경 변수로 등록한다. FIREBASE_API_KEY, 프로젝트 ID와 앱 ID는 브라우저에 전달되는 공개 설정이다. 서버 비밀값 FIREBASE_SERVICE_ACCOUNT_JSON에는 서비스 계정 JSON 전체를 한 줄로 넣고 Vercel에서만 보관한다. 이 JSON 키 파일은 Git에 올리면 안 된다.

Firebase에 firestore.rules, firestore.indexes.json, database.rules.json을 배포한 뒤 공개한다. 계정 프로필은 본인만, 공개 게임 정보와 본인이 참여한 대전 기록은 로그인한 참가자만 읽을 수 있다. 비밀번호 해시·닉네임 선점 문서·노크 도전과 요청 처리 기록은 클라이언트에서 읽거나 쓸 수 없다. 점수 직접 수정과 다른 UID로 접속·채팅하는 것도 막는다. Vercel 배포는 dist/index.html과 api/의 Node.js 24 함수를 사용한다.

현재 여러 사람이 함께 하는 게임은 어디서 도나

Vercel용 Firebase 다인용 연결을 구현했다. 사탕은 서버 API가 Firestore 트랜잭션으로 양쪽 잔액을 함께 변경하며 클라이언트 직접 수정을 차단한다. 실시간 접속은 RTDB로 공유하고 연결 종료 시 정리한다. 배포 환경변수와 규칙을 적용한 뒤 실제 배포에서 확인해야 한다. 기존 Claude 아티팩트용 window.claude 경로와 파일로 여는 혼자 연습 모드도 유지한다.

아티팩트에 다시 게시하는 건 코코가 한다. 고친 내용은 브랜치를 따서 PR로 올리면 머지 뒤 게시한다.

고칠 때

  • 파일은 HTML 하나다. CSS, 스프라이트, 게임 로직이 모두 들어 있다.
  • 스프라이트는 문자 격자와 팔레트로 그린다. 새 코스튬은 기존 스프라이트를 따라 하면 된다.
  • 규칙 숫자(시작 사탕, 장난 시간, 기절 횟수 등)는 스크립트 위쪽 상수에 모여 있다.
  • Firebase 모드의 사탕은 서버가 저장하며, 서버가 발급한 움직임 시드와 입력 기록을 재생해 결과를 계산한다. 기존 Claude·파일 연습 모드는 도전 기록으로 사탕을 계산한다. 자동 입력·다중 계정 방지는 별도 운영 과제다.

1차 플레이 개선

  • 행동 버튼과 진행 대화는 캐릭터 위에 표시하고, 사탕 잡기 미니게임은 화면 중앙에 표시한다.
  • 튜토리얼 뒤 호박 3개 수집 퀘스트가 나타난다. 수집 진행도와 첫 노크 여부는 기존 플레이어 기록으로 복원하고, 튜토리얼 완료 여부는 guideSeen에 저장한다.
  • 문을 두드리면 움직이는 사탕을 초록 포획 바에 가두는 미니게임이 열린다. 시간 제한 없이 게이지가 가득 차면 성공하고 0이 되면 실패한다. 성공하면 상대 사탕 1개를 가져오고, 실패해도 사탕은 이동하지 않는다. 집마다 도전자별 난이도를 기억하며, 성공하면 그 집의 다음 도전이 최대 5단계까지 올라간다. 실패하면 그 집만 1단계로 초기화되고, 다른 집의 난이도는 유지된다. 새 이벤트는 모든 집 난이도를 초기화한다. Firebase 모드는 서버가 도전 난이도·움직임 시드·입력 기록을 관리한다.
  • 아이템 상점에서 사탕 5개로 호박 수호 부적을 사면 5분 동안 그 집에 들어오는 노크 도전을 막는다. 사용 후 20분 동안 다시 쓸 수 없고, 보유 아이템은 이벤트가 바뀌어도 남는다.
  • 튜토리얼, 내 정보, 순위 창에서 최종 사탕 순위에 따른 실제 선물 지급을 안내한다. 노크 전후에는 사탕 이동 대상을, 상점에서는 사탕 차감을 표시한다.
  • 시작 안내는 캐릭터 생성 완료 알림 → 게임 목표·진행 방법 → 퀘스트 도착 알림 → 중앙 이동 가이드 순서다. 이동 가이드는 실제 이동이 시작되면 사라진다.
  • 분장 완료 알림은 최대 4초 표시하며, 화면 어디든 클릭·터치하거나 Space·오른쪽 방향키를 누르면 즉시 튜토리얼로 넘어간다. 별도의 조작 안내 문구는 표시하지 않는다.
  • 인트로 박스 오른쪽 아래의 ‘건너뛰기’는 이야기 연출을 취소하고 이름 입력으로 바로 이동한다. 이후 코스튬 선택과 게임 튜토리얼은 이어진다.

검증

검사와 로컬 서버 실행에는 Node.js 24가 필요하다. Firebase 에뮬레이터 검증에는 Java 21도 필요하다.

npm test
npm run test:emulator

DOM·타이머·Claude 런타임 대역으로 튜토리얼, 퀘스트, 노크, 사탕 이동·순위와 말풍선을 검사한다. Firebase Auth·Firestore·RTDB 에뮬레이터에서는 동시 가입, 재로그인, 동일 집에 대한 동시 노크, 요청 재전송, 사탕 보존·부족, 장식 구매, 이벤트 리셋·종료·최종 결과 보관과 접근 규칙을 확인한다. 브라우저 두 세션으로 접속자 표시, 채팅 전달, 구매에 따른 상대 순위 갱신, 새로고침 후 잔액 복원과 탭 종료 후 접속 해제를 확인했다. 실제 Vercel 환경변수·보안 규칙과 Claude 서버는 별도로 확인해야 한다.

아티팩트 재게시 후 직접 확인할 항목:

  • 데스크톱과 모바일에서 행동·대화 말풍선은 캐릭터 근처에, 사탕 잡기 게임은 화면 중앙에 뜨고 로그인 안내나 HUD에 가려지지 않는지.
  • 처음 접속했을 때 시작 안내들이 순서대로 나타나는지. 인트로 글자 출력 중·문장 사이 모두 건너뛸 수 있고, 이름 입력 중 이전 인트로가 다시 나오지 않는지. 이동 가이드는 설명이 끝난 후 나타나고 실제 이동 시 사라지는지.
  • 튜토리얼 완료 후 퀘스트가 뜨고, 호박 3개 수집 뒤 첫 노크 안내로 바뀌는지. 다인용 모드에서 새로고침해도 진행도가 이어지는지.
  • 실제 두 계정으로 접속해 도전 성공 시 양쪽 사탕과 순위가 갱신되고, 실패 시 잔액이 유지되는지.
  • 이벤트 종료 후 노크·상점이 닫히고 결과가 유지되는지.

About

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages