a301_mmo_game_server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# 서버 빌드 및 실행
cd MMOTestServer
dotnet build -c Debug
dotnet run --project MMOserver/MMOserver.csproj

# 릴리즈 빌드
dotnet build -c Release
dotnet publish -c Release

# Docker
cd MMOTestServer
docker-compose up --build    # 9050/udp, 9500/udp 노출

# 클라이언트 테스터
cd ClientTester/EchoClientTester
dotnet run                                  # 대화형 메뉴
dotnet run -- stress -c 100 -d 60           # 부하 테스트
dotnet run -- stress -c 50 -d 0 -i 100 -r 1000 -b 10  # 상세 옵션

Tech Stack

• C# / .NET 9.0 (C# 13)
• LiteNetLib — UDP 네트워킹
• protobuf-net — 바이너리 패킷 직렬화
• MySQL + Dapper / Dapper.Contrib — 비동기 DB 접근
• Serilog — 로깅 (콘솔 + 파일)

Project Purpose

"One of the plans" 게임의 실시간 MMO 서버. 로비, 채널 관리, 플레이어 동기화 (이동/전투/상태) 담당.

Project Structure

MMOTestServer/
├── MMOserver/              # 게임 서버 실행 프로젝트
│   ├── Game/               # GameServer, Player, Channel, ChannelManager
│   ├── Packet/             # PacketHeader(코드 정의), PacketBody(Protobuf 메시지)
│   ├── Api/                # RestApi (JWT 검증 외부 호출)
│   ├── RDB/                # Handler → Service → Repository → MySQL
│   ├── Utils/              # UuidGeneratorManager, Singleton
│   ├── Program.cs          # 진입점
│   ├── config.json         # DB 연결 설정
│   └── Dockerfile          # 멀티스테이지 빌드
├── ServerLib/              # 재사용 네트워킹 DLL
│   ├── Service/            # ServerBase, Session, SessionManager
│   ├── Packet/             # PacketSerializer
│   └── RDB/                # ARepository<T>, DbConnectionFactory
└── compose.yaml            # Docker Compose

ClientTester/
└── EchoClientTester/       # 테스트 클라이언트
    ├── EchoDummyService/   # Echo RTT 측정
    ├── DummyService/       # 더미 플레이어 이동 시뮬레이션 (10명)
    └── StressTest/         # 부하 테스트 (P50/P95/P99, CSV 내보내기)

핵심 아키텍처

네트워크 코어 (ServerLib)

ServerBase — LiteNetLib INetEventListener 구현. 싱글 스레드 이벤트 폴링 (1ms 간격).

연결 흐름:

UDP Connect → PendingPeer 등록 → 인증 패킷 수신 → Session 생성 → OnSessionConnected

• PendingPeers: Dictionary<int, NetPeer> (peer.Id 기반, 미인증)
• Sessions: Dictionary<long, Session> (hashKey 기반, 인증 완료)
• TokenHash: Dictionary<string, long> (JWT 토큰 → hashKey 매핑)
• 재접속: 같은 hashKey로 재접속 시 기존 peer 교체 (WiFi↔LTE 전환 대응)
• 전송 헬퍼: SendTo(), Broadcast(), BroadcastExcept() (캐시된 NetDataWriter 사용)

Session — 연결별 상태: Token, HashKey, Peer 참조.

• 속도 제한: 슬라이딩 윈도우 (1초), 기본 60 패킷/초
• 3회 위반 시 강제 연결 해제

패킷 프로토콜

바이너리 헤더 + Protobuf 페이로드:

[2B: type (ushort LE)] [2B: size (ushort LE)] [NB: protobuf payload]

패킷 코드 (PacketHeader.cs):

코드	이름	전송 방식	용도
1	ACC_TOKEN	Reliable	JWT 인증
1001	DUMMY_ACC_TOKEN	Reliable	테스트 인증 (hashKey≤1000)
1000	ECHO	ReliableUnordered	RTT 측정
2	LOAD_GAME	Reliable	게임 로드
3	LOAD_CHANNEL	Reliable	채널 목록
4	INTO_CHANNEL	Reliable	채널 입장
5	UPDATE_CHANNEL_USER	Reliable	유저 입장/퇴장 브로드캐스트
6	EXIT_CHANNEL	Reliable	채널 퇴장
7	TRANSFORM_PLAYER	Unreliable	위치/회전 동기화 (HOL 방지)
8	ACTION_PLAYER	ReliableOrdered	공격/스킬/회피 액션
9	STATE_PLAYER	ReliableOrdered	HP/MP 상태
10-12	TRANSFORM/ACTION/STATE_NPC	위와 동일	NPC 동기화
13	DAMAGE	Reliable	데미지
14-15	UPDATE_PARTY/USER_PARTY	Reliable	파티

Protobuf 메시지 (PacketBody.cs):

• PlayerInfo: PlayerId, Nickname, Level, Hp, MaxHp, Mp, MaxMp, Position(Vector3), RotY
• TransformPlayerPacket: PlayerId, Position, RotY
• ActionPlayerPacket: PlayerId, PlayerActionType(IDLE/MOVE/ATTACK/SKILL/DODGE/DIE/REVIVE), SkillId, TargetId
• StatePlayerPacket: PlayerId, Hp, MaxHp, Mp, MaxMp

GameServer (MMOserver/Game/)

ServerBase 확장. 패킷 핸들러 딕셔너리로 라우팅:

• INTO_CHANNEL — 채널 입장, 기존 유저 목록 응답 + 신규 유저 브로드캐스트
• EXIT_CHANNEL — 채널 퇴장, 나머지 유저에게 알림
• TRANSFORM_PLAYER — 위치 브로드캐스트 (Unreliable)
• ACTION_PLAYER — 액션 브로드캐스트 (ReliableOrdered)
• STATE_PLAYER — 상태 브로드캐스트 (ReliableOrdered)

인증 흐름:

• HandleAuth(): JWT를 https://a301.api.tolelom.xyz/api/auth/verify로 검증 (3회 재시도, 5초 타임아웃). 401이면 즉시 실패.
• HandleAuthDummy(): 토큰 값을 hashKey로 직접 사용 (hashKey≤1000만 허용).

채널 시스템

• Channel: Dictionary<long, Player> (hashKey → Player). 기본 최대 100명.
• ChannelManager: 싱글톤. 기본 1개 채널. connectUsers 딕셔너리로 userId→channelId 추적.

DB 레이어

Handler → Service → Repository → MySQL 패턴.

• ARepository<T>: Dapper.Contrib 기반 제네릭 CRUD. 트랜잭션 지원 (WithTransactionAsync).
• DbConnectionFactory: config.json 또는 환경변수에서 연결 문자열 생성. 커넥션 풀: Min=5, Max=100.
• Response<T>: 표준 응답 봉투 ({ Success, Data, Error }).

새 테이블 추가 시: Models/ → Repositories/ (ARepository 상속) → Services/ → Handlers/. ServerLib은 수정 불필요.

스레딩 모델

• 네트워크 루프: 싱글 스레드 폴링 (게임 상태에 락 불필요)
• JWT 검증 / DB: async/await (네트워크 루프 블로킹 없음)
• UUID 생성: ReaderWriterLockSlim

설정

// config.json
{
  "Database": {
    "Host": "localhost",
    "Port": "3306",
    "Name": "game_db",
    "User": "root",
    "Password": "...",
    "Pooling": {
      "MinimumPoolSize": "5",
      "MaximumPoolSize": "100",
      "ConnectionTimeout": "30",
      "ConnectionIdleTimeout": "180"
    }
  }
}

서버 기본 포트: 9500 (UDP). Ping 간격: 3000ms. 연결 타임아웃: 60000ms.

알려진 제한사항

• 서버 측 위치 검증 미구현 (스피드핵/텔레포트 가능)
• 플레이어 데이터 DB 영속화 미구현 (하드코딩된 기본값 사용)
• NPC/파티 패킷 코드 정의됨 but 핸들러 미구현
• 수평 확장 미지원 (단일 서버 인스턴스)