테트리스 웹 프로젝트 종합 문서 (설명 + 실행 + 소스 첨부)

스카이님 요청으로, 기존 1번/2번 글을 하나로 통합한 종합 문서입니다.

  • 프로젝트 소개 및 구조 설명
  • 초보자용 실행/조작 가이드
  • 소스 코드 압축 파일 첨부 링크

소스 코드 다운로드

테트리스 웹 프로젝트 (초보자용 안내서)

안녕하세요! 이 문서는 HTML/CSS/JavaScript만으로 만든 테트리스 웹 게임을 초보 웹 개발자 관점에서 이해하고 실행할 수 있도록 정리한 가이드입니다.

1) 이 프로젝트는 무엇인가요?

이 프로젝트는 브라우저에서 바로 실행되는 테트리스 게임입니다.

  • 별도 프레임워크(React/Vue) 없이 순수 웹 기술로 구성
  • 게임판, 점수, 레벨, 라인 수 표시
  • 다음 블록 미리보기(왼쪽 패널)
  • 키보드 조작(방향키 + WASD + Space + P)
  • 다시 시작 버튼 제공

즉, 웹 기초 + 게임 로직 기초를 한 번에 연습하기 좋은 예제입니다.

2) 폴더 구조

tetris-web/
├─ index.html      # 화면 구조(캔버스/패널/버튼)
├─ styles.css      # UI 스타일(네온 테마, 레이아웃)
├─ app.js          # 게임 핵심 로직
└─ README_BEGINNER_KO.md

3) 파일별 역할

index.html

  • 게임 화면 뼈대
  • 메인 보드 캔버스(#board)
  • 다음 블록 캔버스(#next)
  • 점수/레벨/라인 표시 영역
  • 다시 시작 버튼

styles.css

  • 다크 + 네온 테마 스타일
  • 왼쪽 패널(점수/다음 블록), 오른쪽 게임판 레이아웃
  • 버튼/카드/보더/그림자 등 UI 개선

app.js

  • 블록 모양(테트리미노) 정의
  • 블록 생성/회전/충돌 판정
  • 라인 삭제, 점수·레벨 계산
  • 키보드 입력 처리
  • 다음 블록 미리보기 렌더링
  • 게임 루프(requestAnimationFrame) 실행

4) 실행 방법 (가장 쉬운 방식)

전제: Python 3가 설치되어 있어야 합니다.

터미널에서 아래 실행:

cd /home/bellclawbot/.openclaw/workspace/tetris-web
python3 -m http.server 8080

브라우저 접속:

http://localhost:8080

종료:

  • 터미널에서 Ctrl + C

5) 조작 방법

  • ← 또는 A: 왼쪽 이동
  • → 또는 D: 오른쪽 이동
  • ↓ 또는 S: 한 칸 빠르게 내리기(소프트 드롭)
  • ↑ 또는 W: 회전
  • Space: 바닥까지 즉시 내리기(하드 드롭)
  • P: 일시정지/재개

6) 게임 로직 핵심 이해

(1) 보드

  • 10열 x 20행 2차원 배열로 관리
  • 비어 있으면 0, 블록이 있으면 색상값 저장

(2) 충돌 판정

  • 블록을 이동/회전하기 전에 경계 및 기존 블록과 겹침 검사
  • 충돌이면 이전 상태로 되돌림

(3) 라인 삭제

  • 가득 찬 행을 삭제하고 위 행들을 아래로 당김
  • 삭제 줄 수에 따라 점수 증가
  • 누적 라인에 따라 레벨 상승, 낙하 속도 증가

(4) 다음 블록 미리보기

  • 현재 블록(piece)과 다음 블록(nextPiece)을 분리 관리
  • 현재 블록이 확정되면 nextPiece를 현재로 넘기고 새 nextPiece 생성

7) 초보자가 해보면 좋은 확장 과제

  1. 고스트 블록(착지 예상 위치 표시)
  2. 홀드 기능(블록 1개 보관)
  3. 배경음/효과음 추가
  4. 모바일 터치 조작 버튼 추가
  5. 최고 점수(LocalStorage) 저장
  6. 게임 오버 모달 + 재시작 UX 개선

8) 자주 겪는 문제 해결

Q1. 브라우저가 열렸는데 화면이 안 보여요

  • 주소가 http://localhost:8080인지 확인
  • 서버 터미널이 살아있는지 확인

Q2. 키가 안 먹어요

  • 게임 화면(브라우저 탭)을 먼저 클릭해 포커스 맞추기
  • 한/영 입력 상태와 관계없이 동작하도록 key/code 모두 처리됨

Q3. 포트 충돌이 나요

  • 8080 대신 다른 포트 사용:
python3 -m http.server 8081

9) 프로젝트 소개 문구(복붙용)

"Tetris: Neon Edition"은 순수 HTML/CSS/JavaScript로 만든 브라우저 테트리스입니다. 게임 로직(충돌 판정, 라인 클리어, 점수/레벨 시스템)과 UI 구성(다음 블록 미리보기, 상태 패널, 키보드 입력)을 학습하기에 적합한 입문형 실전 프로젝트입니다.

필요하시면 다음 단계로, 이 프로젝트를 React/TypeScript 버전으로 리팩터링하는 가이드까지 이어서 제공할 수 있습니다.