1. 플러그인 개요
| 항목 | 내용 |
| 플러그인 ID | dx-roulette |
| 플러그인명 | DX Roulette (커스텀 룰렛 포인트 게임) |
| 버전 | 1.0.0 |
| 제작사 | DesignOneX |
| PHP 호환 | PHP 5.6 이상 |
| 필수 의존 | DXCMS, DxPoint (포인트 시스템) |
DX Roulette는 DXCMS 기반 사이트에서 관리자가 슬롯을 직접 구성하고 회원이 포인트를 사용해 룰렛을 돌리는 한국형 포인트 게임 플러그인입니다. 슬롯의 라벨, 색상, 보상 포인트, 당첨 확률(가중치)을 관리자가 자유롭게 설정할 수 있습니다.
2. 주요 기능
2.1 회원 기능
• 화려한 애니메이션 휠 회전 (회전 시간 관리자 설정 가능)
• 당첨 슬롯에 따라 보상 포인트 즉시 지급
• 꽝 슬롯 당첨 시 포인트 미지급 (참가비만 차감)
• 누적 전적 (총 게임 수, 당첨 횟수, 꽝 횟수, 순포인트 증감) 확인
• 최근 게임 기록 10건 조회
• 일일 게임 횟수 제한 도달 시 자동 비활성화
• 보유 포인트 부족 시 게임 버튼 자동 비활성화
2.2 관리자 기능
• 참가비 포인트 설정 (1회 차감 포인트)
• 하루 최대 게임 횟수 설정 (0 = 무제한)
• 룰렛 제목 설정
• 휠 회전 시간(ms) 설정
• 슬롯 추가 · 수정 · 삭제
• 슬롯 드래그 앤 드롭 순서 변경
• 슬롯 활성화 / 비활성화 개별 설정
• 기본 슬롯으로 초기화 (재설치)
• 전체 게임 통계 대시보드
• 회원별 상세 전적 조회
• 슬롯별 당첨 통계
• 게임 로그 전체 조회 및 삭제
3. 설치 방법
3.1 파일 업로드
2. 아래 두 경로에 파일을 업로드합니다.
| 업로드 경로 | 내용 |
| plugins/dx-roulette/ | 플러그인 본체 |
| extend/top/00_roulette_router.php | 프론트 URL 라우터 파일 |
ℹ️ extend/top/ 폴더가 없으면 직접 생성하세요.
3.2 플러그인 활성화
2. DX Roulette 플러그인을 찾아 [활성화] 버튼을 클릭합니다.
3. 활성화 시 DB 테이블 3개가 자동 생성됩니다.
| 생성되는 테이블 | 설명 |
| roulette_settings | 게임 설정 값 저장 |
| roulette_slots | 룰렛 슬롯 구성 데이터 |
| roulette_logs | 게임 플레이 로그 |
4. 최초 활성화 시 기본 슬롯 16개가 자동 삽입됩니다.
3.3 설치 확인
4. 관리자 기본 설정
4.1 설정 항목
| 설정 항목 | 설명 |
| 활성화 (is_active) | 1 = 게임 켜짐, 0 = 게임 꺼짐 |
| 참가비 (play_cost) | 1회 스핀 시 차감되는 포인트 (기본값: 10) |
| 일일 게임 횟수 (daily_limit) | 하루 최대 게임 수, 0 입력 시 무제한 (기본값: 50) |
| 룰렛 제목 (title) | 게임 페이지에 표시되는 제목 (기본값: 럭키 룰렛) |
| 휠 회전 시간 (spin_duration) | 룰렛 회전 애니메이션 시간(ms) (기본값: 4000 = 4초) |
⚠️ 참가비(play_cost)를 0으로 설정하면 무료로 게임을 즐길 수 있습니다. 사이트 정책에 맞게 설정하세요.
5. 슬롯 관리
5.1 슬롯이란?
5.2 슬롯 항목 설명
| 항목 | 설명 |
| 라벨 (label) | 룰렛 휠에 표시되는 텍스트 (예: +100P, 꽝, 대박) |
| 배경색 (color) | 슬롯 칸의 배경 색상 (HEX 코드) |
| 글자색 (text_color) | 슬롯 라벨의 글자 색상 (HEX 코드) |
| 보상 포인트 (reward) | 당첨 시 지급되는 절대 포인트 (0이면 꽝) |
| 당첨 가중치 (prob_weight) | 높을수록 자주 당첨 (상대적 확률 비율) |
| 활성화 (is_active) | 1 = 게임에 포함, 0 = 휠에서 제외 |
| 순서 (sort) | 휠에 표시되는 순서 (드래그 앤 드롭으로 변경) |
5.3 당첨 확률 계산 방식
ℹ️ 당첨 확률(%) = 해당 슬롯의 prob_weight ÷ 전체 활성 슬롯 prob_weight 합계 × 100
예시: 전체 가중치 합이 100이고 꽝 슬롯의 가중치가 30이면 꽝 당첨 확률은 30%입니다.
5.4 기본 제공 슬롯 (16개)
| 라벨 | 보상 포인트 | 가중치 | 당첨 확률 참고 |
| 꽝 | 0P | 30 | 약 16% |
| 꽝 | 0P | 25 | 약 13% |
| 꽝 | 0P | 25 | 약 13% |
| +10P | 10P | 20 | 약 11% |
| +30P | 30P | 15 | 약 8% |
| +50P | 50P | 15 | 약 8% |
| +100P | 100P | 12 | 약 6% |
| +200P | 200P | 10 | 약 5% |
| +300P | 300P | 8 | 약 4% |
| +500P | 500P | 6 | 약 3% |
| +500P | 500P | 6 | 약 3% |
| +1,000P | 1000P | 4 | 약 2% |
| +2,000P | 2000P | 3 | 약 2% |
| +3,000P | 3000P | 2 | 약 1% |
| +5,000P | 5000P | 2 | 약 1% |
| +10,000P | 10000P | 1 | 약 0.5% |
⚠️ 기본 슬롯은 [기본값으로 초기화] 버튼으로 언제든 복원할 수 있습니다. 단, 기존 슬롯 데이터는 모두 삭제됩니다.
5.5 슬롯 추가
5.6 슬롯 수정 및 삭제
⚠️ 삭제된 슬롯은 복구할 수 없습니다. 기록에 남은 로그에는 삭제된 슬롯 이름이 텍스트로 보존됩니다.
5.7 슬롯 순서 변경
6. 관리자 대시보드
6.1 통계 탭
• 전체 당첨 횟수 / 꽝 횟수
• 총 참가비 합계 (회원들이 지불한 포인트 총량)
• 총 당첨 포인트 합계 (회원들에게 지급된 포인트 총량)
• 전체 포인트 증감 합계 (운영자 관점 순이익)
• 슬롯별 당첨 횟수 통계
6.2 회원 탭
• 회원별 총 게임 수, 당첨 횟수, 총 참가비, 총 당첨 포인트, 순포인트
• 회원 이름 클릭 시 상세 전적 및 게임 로그 조회
6.3 슬롯 탭
• 슬롯 추가, 수정, 삭제, 순서 변경
• 기본 슬롯으로 초기화
6.4 로그 탭
• 날짜 · 회원 · 당첨 슬롯 · 참가비 · 당첨 포인트 · 순증감 확인
• 로그 전체 삭제 기능 (복구 불가)
7. 게임 진행 방식
7.1 접속 URL
ℹ️ 로그인한 회원만 게임 페이지에 접속할 수 있습니다. 비로그인 시 로그인 페이지로 자동 이동합니다.
7.2 게임 순서
2. 현재 보유 포인트 및 참가비, 일일 남은 횟수를 확인합니다.
3. [룰렛 돌리기] 버튼을 클릭합니다.
4. 참가비 포인트가 즉시 차감됩니다.
5. 설정된 시간(기본 4초) 동안 휠이 회전합니다.
6. 가중치 기반 랜덤으로 당첨 슬롯이 결정됩니다.
7. 보상 포인트가 있으면 즉시 지급, 꽝이면 미지급입니다.
8. 결과 모달에서 당첨 슬롯과 포인트 변동을 확인합니다.
7.3 포인트 처리
| 상황 | 포인트 처리 |
| 항상 (스핀 시) | 참가비(play_cost) 차감 |
| 보상 슬롯 당첨 시 | 해당 슬롯의 reward 포인트 지급 |
| 꽝(reward=0) 당첨 시 | 추가 포인트 없음 (참가비만 차감) |
| 순 포인트 변동 | 지급 포인트 - 참가비 |
7.4 게임 불가 조건
| 조건 | 결과 |
| 게임 비활성화 (is_active=0) | 룰렛 버튼 비활성화 및 안내 표시 |
| 보유 포인트 < 참가비 | 버튼 비활성화 (포인트 부족 안내) |
| 일일 제한 도달 | 버튼 비활성화 (한도 초과 안내) |
8. 파일 구조
| 파일/폴더 | 설명 |
| plugin.php | 플러그인 진입점, 훅 등록, 사이드바 메뉴 |
| manifest.php | 플러그인 메타 정보 |
| core/install.php | DB 설치, 설정 헬퍼, 슬롯 헬퍼, 랜덤 픽 함수 |
| admin/index.php | 관리자 페이지 (통계/슬롯/설정/로그) |
| admin/layout.php | 관리자 레이아웃 헤더 |
| admin/layout_end.php | 관리자 레이아웃 푸터 |
| admin/partials/log_table.php | 게임 로그 테이블 컴포넌트 |
| views/index.php | 프론트 룰렛 게임 화면 |
| extend/top/00_roulette_router.php | 프론트 URL 라우터 (/roulette) |
9. 데이터베이스 구조
9.1 roulette_settings (게임 설정)
| 컬럼 | 설명 |
| skey | 설정 키 (is_active, play_cost, daily_limit 등) |
| svalue | 설정 값 (TEXT) |
9.2 roulette_slots (슬롯 구성)
| 컬럼 | 설명 |
| id | 자동 증가 PK |
| label | 슬롯 표시 텍스트 (예: +100P, 꽝) |
| color | 슬롯 배경색 (HEX) |
| text_color | 슬롯 글자색 (HEX) |
| reward | 당첨 보상 포인트 (0이면 꽝) |
| prob_weight | 당첨 가중치 (높을수록 자주 당첨) |
| sort | 표시 순서 |
| is_active | 활성화 여부 (1=활성, 0=비활성) |
9.3 roulette_logs (게임 로그)
| 컬럼 | 설명 |
| id | 자동 증가 PK |
| member_id | 회원 ID |
| slot_id | 당첨 슬롯 ID |
| slot_label | 당첨 슬롯 라벨 (텍스트 보존) |
| play_cost | 차감된 참가비 포인트 |
| win_amount | 지급된 보상 포인트 |
| point_delta | 순 포인트 증감 (win_amount - play_cost) |
| created_at | 게임 일시 |
10. 버전 업그레이드 시 주의사항
기존 버전(payout 컬럼 사용)에서 업그레이드 시 플러그인이 자동으로 DB 마이그레이션을 수행합니다.| 마이그레이션 내용 | 설명 |
| roulette_slots.reward 컬럼 추가 | payout → reward 컬럼 명칭 변경 및 데이터 복사 |
| roulette_logs.play_cost 추가 | 참가비 별도 기록 컬럼 추가 |
| roulette_logs.win_amount 추가 | 당첨 포인트 별도 기록 컬럼 추가 |
| 구 컬럼(bet, payout) 제거 | 자동 DROP 처리 |
ℹ️ 업그레이드 시 별도 작업 없이 플러그인 재활성화만으로 자동 마이그레이션이 완료됩니다.
11. 트러블슈팅
| 증상 | 해결 방법 |
| 게임 페이지 404 오류 | extend/top/00_roulette_router.php 파일 위치 확인 |
| 포인트가 지급되지 않음 | DxPoint 클래스 설치 여부 확인 |
| DB 오류 발생 | 플러그인 비활성화 후 재활성화로 테이블 재생성 |
| 게임 메뉴가 사이드바에 없음 | 플러그인 활성화 여부 및 plugin.php 훅 확인 |
| 슬롯이 휠에 나타나지 않음 | 해당 슬롯의 is_active가 1인지 확인 |
| 모든 슬롯을 원래대로 되돌리고 싶음 | 슬롯 탭 → [기본값으로 초기화] 클릭 |
| 일일 제한 초과 후에도 게임 가능 | daily_limit 설정값 확인, 0이면 무제한 |
| 휠 회전이 너무 빠르거나 느림 | spin_duration 값 조정 (단위: ms, 1000=1초) |
12. 라이선스
| 항목 | 내용 |
| 재배포·판매 | ❌ 금지 (원천 소스 90% 이상 수정 시 재배포 및 판매 가능) |
| 플러그인 원천 시스템 | DesignOneX 소유 |
| 상업적 사용 | ✅ 상업적 제작에만 허용, 학습용 |
| 학습용 라이선스 | 디자인원엑스 라이선스 |
⚠️ 플러그인 코어(plugin.php, core/, admin/) 자체의 재배포 및 판매는 금지됩니다.
본 플러그인은 디자인원엑스 라이선스를 따릅니다. 상업적 제작 목적으로만 사용 가능하며, 원천 소스의 90% 미만 수정본의 재배포 및 판매는 엄격히 금지됩니다. 플러그인의 저작권 및 소유권은 DesignOneX에 귀속됩니다.
