Lucky Wheel

1. What this page does

The Lucky Wheel page allows administrators to configure and manage the interactive promotional wheel in the lobby. Administrators can set spin costs in tickets or diamonds, configure up to 16 wheel slots, calibrate odds weights for each slot, configure suspenseful spin animations (such as near misses, stopping just short, or rolling back), test the experience via live preview demo spins, and fulfill big physical prizes won by players. It also provides performance analytics and spin history.

The page consists of two main tabs:

• Wheel & Prizes tab — Wheel configuration and prize slots editor.
• Report & Spin History tab — Performance report and spin history logs.

---

2. Before you start

• Required Permissions:
  • You must have the 'Spinner' permission in Roles to view, modify prize slots, adjust spin tricks, and save wheel settings.
  • You must have the 'Spinner - report and history' permission in Roles to access analytics reports, view spin logs, and mark big prizes as delivered.
• Prerequisites:
  • Prize Slots: Plan at least 2 slots (up to 16 slots) across 4 reward types:
    • Physical Prizes: Tangible gifts such as smartphones or gold bars (requires a label and a full prize name).
    • Points: Loyalty points credited directly to the player's wallet.
    • Tickets: Wheel tickets credited directly to the player's wallet for future spins.
    • Diamonds (Score): Diamond balance credited directly to the player's wallet.
  • Images: Prepare square transparent PNG or WebP images (600x600 px recommended, at least 400x400 px) for custom prize artwork.
• Key Rules:
  • The wheel must have at least 2 slots, and at least 1 slot must have odds greater than 0.
  • Points, tickets, and diamonds are automatically credited upon winning. Physical prizes require administrative fulfillment and manual confirmation (Mark as delivered).

---

3. Screen layout

The interface is structured into two main tabs:

1. Wheel & Prizes Tab:
   • Hero Card: Displays wheel status, total slots count, cost per spin, last updater, and a theme-matching glow preview.
   • Wheel Settings Card: Inputs for Wheel Name (Thai/English), price per spin in tickets, price per spin in diamonds, and the Open to players active switch.
   • Wheel Slots List: Cards for each slot arranged clockwise from the pointer, featuring drag-and-drop handles, reordering arrows, and an Add slot button.
   • Spin Tricks Card: Sliders for spin duration (3–9 seconds) and 3 suspense animations (Near miss, Stops just short, Crosses then rolls back) with individual Show me demo buttons.
   • Player View & Prize Ladder: Interactive live wheel rendered in site theme colors, big prize rankings, and a Try a spin demo button.
   • Delete Wheel Setup Card: Located at the bottom; allows deleting the wheel configuration when inactive.
2. Report & Spin History Tab:
   • Summary Metric Cards: Total spins, unique players, currency paid (tickets and diamonds), rewards given out, and big prizes won.
   • Daily and Hourly Spin Charts: Line charts tracking spin activity over time.
   • Breakdown Tables: Prizes won summary table and Top 10 claimant players.
   • Spin History Section: Sub-tabs for Points & tickets and Big prizes (with filters: All, Not handed over yet, Handed over) and a CSV export button.

---

4. Search and filters

Filters on Report & Spin History Tab

Field / Filter	Type	Options / How to use	Result
Period / Date Range	Quick preset buttons	Choose: Today, 7 days, 30 days, or Custom	Filters summary cards, charts, and history tables by date range.
Search player...	Text input	Type a player username	Filters history table to show spins made by that user.
Paid With	Dropdown	Select: All, Tickets, or Diamonds	Filters history table by currency used to spin.
Delivery Status Tabs	Filter tabs	Select: All, Not handed over yet, or Handed over	Filters big prize records by fulfillment status.
Refresh	Button	Click the refresh button	Instantly reloads the latest report and table data.

---

5. Data tables

1. Big Prizes Delivery Table (Report & History Tab > Big Prizes)

Column	What you see	Meaning	Badge or Symbol
Date & Time	Timestamp (e.g. 21/10/2026, 17:15)	Time when the player spun and won the prize	Standard date/time format
Player	Player username (e.g. lucky_winner)	Account that won the big physical prize	Bold username text
Prize	Thumbnail image and prize name	Physical prize won by the player	Thumbnail and bold title
Paid With	Ticket or diamond cost paid	Currency spent for the spin	• Blue: Wheel ticket • Purple: Diamond
Delivery Status	Delivery badge	Physical delivery tracking status	• Orange (Pending): Awaiting shipment/handover • Green (Delivered): Handed over to player
Handled By	Admin username and timestamp	Record of who marked the prize as delivered	Username and timestamp
Actions	Mark as delivered button	Action button to confirm fulfillment	Pinned button on pending records

2. General Spin Log Table (Report & History Tab > Points & Tickets)

Column	What you see	Meaning	Badge or Symbol
Date & Time	Date and time of spin	Timestamp of transaction	Standard date format
Player	Player username	Account that performed the spin	Username text
Reward Won	Reward type and amount (e.g. +50 Points)	Currency credited to wallet	• Orange: Points • Blue: Tickets • Purple: Diamonds
Paid With	Currency and amount spent	Cost deducted for the spin	Blue or purple badge

---

6. Step-by-step

1. Setting up a new lucky wheel

1. Navigate to Activities > Lucky wheel in the Wheel & prizes tab.
2. If no wheel exists yet, the screen displays setup steps. Click Set up the wheel.
3. In the Wheel settings card:
   • Enter Wheel name (Thai) (required, e.g. วงล้อนำโชคเศรษฐี).
   • Enter Wheel name (English) (optional, e.g. Millionaire Lucky Wheel).
   • Enter Price per spin (tickets) (e.g. 1).
   • Enter Price per spin (diamonds) (e.g. 10).
   • Keep the Open to players switch off while configuring slots.
4. Proceed to configure slots as described in Step 2.

2. Adding and configuring wheel slots

1. Under Wheel slots, click Add slot (the wheel must have between 2 and 16 slots).
2. Click the pencil icon or expand the slot card to configure fields:
   • Reward type: Choose Prize (Physical), Points, Tickets, or Diamonds.
   • Label on the wheel: Enter a concise label (max 60 characters, e.g. iPhone 17 or 100 Points).
   • For Prize (Physical):
     • Enter Prize name: Full description of the item (e.g. iPhone 17 Pro Max 256GB).
     • Select Big prize rank: Priority rank (Prize 1 appears most prominently in the prize ladder).
     • Upload Image on the wheel: Transparent square PNG/WebP up to 5 MB.
   • For Points, Tickets, or Diamonds:
     • Enter Amount: Whole number greater than 0.
   • Odds weight: Enter a probability weight value (e.g. 15). The percentage share relative to all slots is calculated automatically (e.g. currently 5.2%).
3. Click Done to collapse the card.

3. Reordering wheel slots

1. Slots appear in clockwise order starting from the pointer at 12 o'clock.
2. Reorder slots by:
   • Clicking and dragging the 6-dots handle up or down.
   • Using the Move up and Move down arrow buttons on each card.
3. Observe the live preview on the right update its sector order immediately. Interleave big physical prizes with standard rewards so that trick animations can trigger.

4. Configuring spin tricks and demo spins

1. Scroll down to the Spin tricks card:
   • Adjust the Spin length slider between 3.0 and 9.0 seconds (default is 5.2 seconds).
   • Calibrate the frequency percentage for the 3 tease tricks:
     • Near miss: Wheel lands on the big prize before the winner, pointer quivers, then creeps to the winning slot.
     • Stops just short: Wheel decelerates and stops just before the big prize next to it.
     • Crosses, then rolls back: Wheel crosses into the big prize, holds briefly, then rolls back into the winning slot.
2. Click Show me beside any trick to preview its animation on the wheel canvas.
3. In the Player view box on the right, click Try a spin to run a simulated spin (draws according to your odds and plays configured tricks without consuming currency or logging data).
4. When satisfied, toggle Open to players to Open (Green).
5. Click Save on the bottom action bar.

5. Fulfilling big physical prizes

1. When a player wins a physical prize, the system records the transaction with status Not handed over yet.
2. Go to Report & spin history and select the Big prizes tab.
3. Click the Not handed over yet filter tile.
4. Review the winning player username and prize details.
5. Once physical delivery or shipment is complete, click Mark as delivered on that row.
6. In the confirmation dialog, verify the recipient information and confirm.
7. Status updates to Handed over (Green), stamped with your username and timestamp.

6. Deleting the wheel setup

1. To remove the wheel entirely, toggle the Open to players switch to Closed (Gray) and click Save.
2. Scroll to the bottom card: Delete setup.
3. Click the red Delete setup button and confirm in the dialog.
4. The wheel configuration is cleared, returning the page to the initial setup state (past spin history remains saved in the database).

---

7. Edit / Add forms

1. Wheel Settings Fields

Field	Required?	What to enter	Example	Rules & Constraints
Wheel name (Thai)	Required	Title in Thai	วงล้อนำโชคเศรษฐี	Max 100 characters
Wheel name (English)	Optional	Title in English	Millionaire Lucky Wheel	Max 100 characters (falls back to Thai name if empty)
Price per spin (tickets)	Required	Tickets deducted per spin	1	Whole number >= 0
Price per spin (diamonds)	Required	Diamonds deducted per spin	10	Whole number >= 0
Open to players	Required	Active status switch	Open (Green)	On or Off

2. Slot Form Fields

Field	Required?	What to enter	Example	Rules & Constraints
Reward type	Required	Slot reward category	Prize	Choose: Prize, Points, Tickets, or Diamonds
Label on wheel	Required	Text printed on wheel segment	iPhone 17	Max 60 characters
Prize name	Required (if Prize)	Complete item title	iPhone 17 Pro Max 256GB	Max 100 characters
Big prize rank	Required (if Prize)	Priority rank in prize ladder	Prize 1	Number from 1 to physical prize count
Amount	Required (if numeric)	Reward quantity	100	Whole number > 0
Odds weight	Required	Probability weight value	15	Number >= 0; share % calculated automatically
Image on wheel	Optional	Custom segment artwork	Upload file	Transparent PNG/WebP up to 5 MB

---

8. Popups and dialogs (Popup / Modal)

1. Confirm Prize Delivery Dialog

• When it opens: When clicking Mark as delivered on a pending big prize record.
• What you see: Prize name, player username, and confirmation note that the action is final.
• What to do: Ensure physical delivery is complete, then confirm.
• Result: Status changes permanently to Handed over.

2. Delete Wheel Setup Confirmation Dialog

• When it opens: When clicking Delete setup while the wheel is inactive.
• What you see: Warning prompt stating wheel configuration and slots will be cleared.
• What to do: Confirm deletion.
• Result: Deletes active wheel setup while preserving historical spin logs.

3. Version Conflict Dialog

• When it opens: When saving wheel settings or slots that were modified by another administrator in the interim.
• What you see: Outdated version alert.
• What to do: Click Load latest to pull the latest changes, then re-apply edits.
• Result: Prevents concurrent edit overwrites.

---

9. Statuses and badges

1. Lucky Wheel Operational Status

Status Badge	Color	Meaning	Next Action
Open	Green	Wheel is active and accessible to players in the lobby.	Normal operation.
Closed	Gray	Wheel is closed; players see it is not open yet.	Toggle switch to open when ready.

2. Big Prize Delivery Statuses

Status Badge	Color	Meaning	Next Action
Pending (Not handed over yet)	Orange	Player won a physical prize; awaiting delivery.	Fulfill item and click Mark as delivered.
Delivered (Handed over)	Green	Staff confirmed physical prize was handed to player.	Terminal fulfilled state.

3. Reward Type Colors & Badges

Reward Type	Tone Color	Icon	Fulfillment Method
Prize (Physical)	Pink	Gift box	Manual delivery by staff
Points	Orange	Star	Instant wallet credit
Tickets	Blue	Ticket	Instant wallet credit
Diamonds (Score)	Purple	Sparkles	Instant wallet credit

---

10. Frequently asked questions / Troubleshooting

• Why does saving fail with red borders around slots?
  • Verify two fundamental requirements:
    1. The wheel must have at least 2 slots (up to 16).
    2. At least 1 slot must have an odds weight greater than 0.
    • Also ensure all required slot fields (such as prize name for physical items) are completely filled.
• Why does a trick animation show "No everyday prize sits next to a big prize in this position"?
  • Suspense tricks (near miss, stops just short, roll back) only trigger when a winning standard prize sits immediately adjacent to a big physical prize on the wheel rim. Reorder slots so that physical prizes alternate with standard rewards.
• Why can't I click Delete Setup?
  • The delete button is disabled while the wheel is active. Switch Open to players to Closed (Gray), click Save, and then the delete button will become active.
• Can a delivered prize status be undone?
  • No. Once marked as delivered, the record is permanently sealed with the fulfilling administrator's username and timestamp.