직접 칠한 정육면체로 맵에 위장하는 25인 비대칭 PvP 숨바꼭질 게임입니다. UE5 C++ 클라이언트와 독립 C#/.NET 서버를 사용합니다. 술래 1명이 도망자 14명을 찾으며, 도망자는 이동을 멈추고 경기 중에도 외형을 다시 칠할 수 있습니다.
기준 버전은 csharp-v1.0.0입니다. 구현 범위·검증 증거·제약은 최종 검증 보고서를 기준으로 합니다. 최초 기획의 모든 항목을 구현한 상용 서비스 버전은 아닙니다. C++ 서버는 이후 별도 대체 구현으로 진행합니다.
| 구분 | 구현 |
|---|---|
| 게임 흐름 | PlayerID 신규/기존 선택 → 방 생성/입장/Ready → 준비 → 탐색 → 결과/보상 → 로비 |
| 클라이언트 | 약 45도에서 시작하는 유닛 중심 카메라, 마우스 회전, 시점 기준 WASD 이동 |
| 위장 | 16×16 버퍼에 면당 4×4인 정육면체 전개도, 16색, 1×1/2×2 브러시, 동적 텍스처 |
| 게임 서버 | 20Hz 방별 single-writer, 서버 권위 이동·충돌·잉크·채색·탐색·승패 |
| 위치 신호 | 탐색 중 25초 주기, 3초 사전 경고, 최근 이동량에 따른 오차 범위 |
| 경제 | PostgreSQL 코인 지갑, 멱등 경기 보상·구매, revision 기반 장착 |
| 검증 도구 | xUnit 128개, 실제 TCP transport 검사, C# LoadBot, 경제 재로그인/재시작 smoke |
도망자는 탐색 중 술래 화면에 실제로 보입니다. 그림을 주변 사물과 비슷하게 칠해 숨는 게임입니다. 준비 시간에는 술래 화면을 검게 가립니다. 상점의 외형은 정육면체 기반 디버그 표현이며, 다양한 완성형 캐릭터 아트는 포함하지 않습니다.
Windows 11, .NET SDK 10.0.400, Docker Desktop과 PostgreSQL 16.6-alpine을 사용했습니다. 클라이언트 소스 빌드는 UE 5.8.1, Visual Studio Community 2026, MSVC 14.50.35717, Windows SDK 10.0.22621.0 환경에서 검증했습니다. 패키징된 클라이언트 실행에는 UE 에디터가 필요하지 않습니다.
아래 명령은 저장소 루트에서 실행합니다. .env가 이미 있으면 복사하지 않습니다.
cd D:\Portfolio\ProjectPixelVeil
if (!(Test-Path .env)) { Copy-Item .env.example .env }
# .env의 PIXELVEIL_POSTGRES_PASSWORD를 로컬 개발용 값으로 설정합니다.
docker compose up -d
dotnet user-secrets set --project .\src\PixelVeil.Server\PixelVeil.Server.csproj "ConnectionStrings:PixelVeil" "Host=127.0.0.1;Port=54329;Database=pixelveil;Username=pixelveil;Password=<local-password>"
dotnet run --project .\src\PixelVeil.Server\PixelVeil.Server.csproj<local-password>는 .env와 같은 값으로 대체합니다. 초기화 시 EF Core migration과 기본 카탈로그가 적용됩니다. 같은 포트의 서버를 두 번 실행하면 실패합니다. 연결 문자열 오류가 나면 위 user secrets 설정과 Development 실행 프로필을 확인합니다.
최종 로컬 배포 폴더는 artifacts/releases/csharp-v1.0.0/입니다. 폴더 전체를 보관해야 합니다. Client/PixelVeilClient.exe 하나만 복사하면 실행되지 않습니다. 배포 파일은 Git에 넣지 않습니다.
# 각 명령으로 클라이언트를 하나씩 실행합니다. 기본 제한은 각각 30 FPS입니다.
& '.\artifacts\releases\csharp-v1.0.0\Client\PixelVeilClient.exe' -windowed -ResX=1280 -ResY=7203클라이언트 시연은 서로 다른 PlayerID를 사용합니다. 기존 데이터는 같은 PlayerID를 선택하면 다시 불러옵니다. 신규 생성은 새 지갑을 만듭니다. -PixelVeilMaxFPS=60으로 60 FPS, -PixelVeilMaxFPS=0으로 제한 해제가 가능합니다. 3개 창 동시 실행은 기본 30 FPS로 시작합니다.
배포된 서버를 실행할 때는 소스 프로젝트의 user secrets가 자동 적용되지 않습니다. 해당 PowerShell 세션에 연결 문자열을 설정합니다.
$env:ConnectionStrings__PixelVeil = 'Host=127.0.0.1;Port=54329;Database=pixelveil;Username=pixelveil;Password=<local-password>'
& '.\artifacts\releases\csharp-v1.0.0\Server\PixelVeil.Server.exe'서버는 127.0.0.1:7777만 사용합니다. DB는 Docker volume에 보관합니다. docker compose down은 컨테이너를 종료하며, docker compose down -v는 저장된 플레이 데이터까지 삭제하므로 데이터 유지 시 사용하지 않습니다.
| 입력 | 동작 |
|---|---|
| WASD | 카메라 시점 기준 이동 |
| 마우스 이동 | 유닛 중심 카메라 회전 |
| E | 도망자 그림 편집 시작/종료, 편집 중 이동 불가 |
| 편집 UI 클릭/드래그 | 색·브러시 선택 및 전개도 채색 |
| 화면 중심 조준 + Space | 술래 탐색 요청, 판정은 서버에서 수행 |
dotnet build .\PixelVeil.slnx -c Release --disable-build-servers
dotnet test .\PixelVeil.slnx -c Release --no-build --no-restore --disable-build-servers
pwsh -File .\conformance\Test-V1Transport.ps1부하 검증은 전용 서버/DB 사용을 권장합니다. 새 테스트 플레이어와 경기 보상 원장을 생성합니다.
dotnet run -c Release --project .\tools\PixelVeil.LoadBot -- --bots 50 --rooms 10 --duration 10m --move-hz 20 --report .\artifacts\loadtest\result.json경제 smoke 도구는 실제 경기에서 200 Coin 이상 얻은 검증용 PlayerID의 코인을 사용합니다. 사용자 계정을 대상으로 실행하지 않습니다. 최종 검증 보고서의 재현 절차를 참고합니다.
UE 소스 빌드는 .uproject 우클릭 → Generate Visual Studio project files → PixelVeilClient의 Development Editor / Win64 빌드입니다. 컴퓨터별 EngineAssociation이 맞지 않으면 UE 5.8을 선택해 연결합니다. 에디터가 실행 중이면 Live Coding(Ctrl+Alt+F11)을 사용하며, 전체 빌드 전에는 에디터를 종료합니다.
UE/PixelVeilClient/ UE C++ 네트워크, Slate/UMG UI, 카메라·큐브 표현
src/PixelVeil.Protocol/ C# wire/payload codec
src/PixelVeil.Server/ TCP, 세션, 방 시뮬레이션, DB·정산
tests/ 프로토콜·도메인·동시성 자동 테스트
tools/PixelVeil.LoadBot/ 실제 TCP 다중 방 부하 및 오류 패킷 검사
tools/PixelVeil.EconomySmoke/ 실제 TCP 구매·장착·재로그인 검증
protocol/ 언어 중립 계약·golden fixture
conformance/ 실제 TCP transport 시나리오
docs/releases/ C# 기준 버전과 검증·시연 안내
로컬 PlayerID 선택은 비밀번호 인증이 아닙니다. 경기 중 재접속 복구, 인터넷 품질 검증, 관리자 API/CLI, CI는 현재 범위에서 제외했습니다. 술래는 탐색 중 도망자의 렌더링 데이터를 받으므로 변조 클라이언트의 ESP까지 방지하지 않습니다. DB 중단·서버 강제 종료 시 미정산 경기를 자동 복구하는 durable outbox는 없습니다. DB를 정상 실행한 로컬 시연 환경을 기준으로 합니다.
128개 xUnit 테스트에는 실제 PostgreSQL 트랜잭션 전체 장애 주입 검증이 포함되지 않습니다. transport 통과를 전체 C#/C++ conformance 통과로 표현하지 않습니다. 시연 영상 촬영·편집과 C++ 서버 구현은 후속 작업입니다.