Gifting System
Relevant source files
The following files were used as context for generating this wiki page:- components/gift-shop.tsx
- components/gift-sender.tsx
- types/gift.ts
- components/gifts-page.tsx
- components/user-profile.tsx
- components/friends-page.tsx
Note: The file components/gift-animation.tsx was requested but not found in the provided source files. Information about gift animations is derived from the animation property in the Gift type definition.
The Gifting System is a social and economic feature within the application that allows players to purchase virtual items using in-game chips and send them to other players. This system is designed to enhance player interaction and provide a mechanism for players to express appreciation or celebrate moments with others.
The system is composed of several key UI components: a GiftShop for browsing and purchasing, a GiftSender modal for managing the sending process, and a GiftsPage for viewing and managing received gifts. Gifts are categorized by type and rarity, with prices varying accordingly. The entire flow is integrated into the player's profile and social features like the friends list.
System Architecture
The Gifting System is primarily a front-end implementation composed of several React components that manage state and user interactions. The core components work together to provide a seamless user experience from purchase to delivery.
Component Interaction
The following diagram illustrates how the main components of the Gifting System interact with each other.
This diagram shows the primary entry points (UserProfile, FriendsPage, GiftsPage) that can trigger the GiftSender modal. The GiftSender utilizes the GiftShop to allow gift selection and then handles the sending logic, which culminates in a system message being sent to the chat.
Sources: components/user-profile.tsx:300-307, components/friends-page.tsx:254-262, components/gifts-page.tsx:285-289, components/gift-sender.tsx:31-40
Key Components
| Component | Description | Source File |
|---|---|---|
GiftShop | Displays a catalog of purchasable gifts, allowing users to browse, search, and filter. It checks if the player can afford a gift. | components/gift-shop.tsx |
GiftSender | A dialog component that orchestrates the gift-sending process, including gift selection, recipient choice, and adding a message. | components/gift-sender.tsx |
GiftsPage | A full-page view for a user to see all their received gifts, with options to filter by category and sale status. | components/gifts-page.tsx |
UserProfile | Displays a summary of a player's received gifts and provides an entry point to the GiftsPage. | components/user-profile.tsx |
Data Model
The core of the system is the Gift data structure, which defines the properties of each virtual item.
Sources: types/gift.ts
ER Diagram
The diagram below shows the data structures related to the gifting feature.
Gift Type
This interface defines the attributes of a single gift item available in the shop.
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier for the gift. |
name | string | The display name of the gift. |
icon | string | The emoji or icon representing the gift. |
description | string | A short description of the gift. |
price | number | The cost of the gift in player chips. |
category | "fun" | "romantic" | "luxury" | "celebration" | The category the gift belongs to. |
rarity | "common" | "rare" | "epic" | "legendary" | The rarity level of the gift, affecting its appearance and price. |
animation | string (optional) | An optional property for a special animation when the gift is sent/received. |
Sources: types/gift.ts:1-11
Gift Shop (GiftShop Component)
The GiftShop component is the central marketplace for all virtual gifts. It presents a categorized and searchable list of items that players can purchase.
Sources: components/gift-shop.tsx
Features
- Search and Filter: Players can search for gifts by name and filter them by category.
- Categorization: Gifts are organized into logical tabs:
All,Fun,Love,Luxury, andParty. - Rarity System: Gifts have a rarity (
common,rare,epic,legendary) which is visually indicated by color-coding and effects. Legendary items have a pulsing glow. - Affordability Check: The UI disables the purchase button for gifts that the player cannot afford with their current chip balance.
- Player Balance Display: The player's current chip balance is displayed prominently.
Sources: components/gift-shop.tsx:21-186, components/gift-shop.tsx:208-220, components/gift-shop.tsx:250-253
Gift Categories & Rarities
The shop uses predefined categories and rarities to organize gifts.
| Categories | Rarities |
|---|---|
| Fun | Common |
| Romantic (Love) | Rare |
| Luxury | Epic |
| Celebration (Party) | Legendary |
Sources: components/gift-shop.tsx:21-186, components/gift-shop.tsx:188-201
The rarity of a gift determines its border color in the UI, providing a quick visual cue to the player.
// Example of rarity color logic
const getRarityColor = (rarity: string) => {
switch (rarity) {
case "common":
return "text-gray-400 border-gray-400";
case "rare":
return "text-blue-400 border-blue-400";
case "epic":
return "text-purple-400 border-purple-400";
case "legendary":
return "text-yellow-400 border-yellow-400";
default:
return "text-gray-400 border-gray-400";
}
}
Sources: components/gift-shop.tsx:188-201
Gift Sending Flow (GiftSender Component)
The GiftSender component manages the multi-step process of sending a gift. It acts as a state machine, guiding the user through selecting a gift, choosing a recipient, and confirming the transaction.
Sources: components/gift-sender.tsx
State Management
The component uses a step state to control the UI flow:
select-gift: The initial state, where theGiftShopis displayed.select-player: If no recipient was pre-selected, this step allows the user to choose a player from the current game.confirm: The final step to review the gift, recipient, and an optional message before sending.
Sources: components/gift-sender.tsx:18-23
Sending Process Flowchart
This flowchart visualizes the logic within the GiftSender component.
Sequence Diagram
The following diagram shows the sequence of user actions and component interactions when sending a gift.
Sources: components/gift-sender.tsx:31-65
Receiving and Managing Gifts
Once a gift is sent, it appears in the recipient's collection, which can be viewed from their user profile.
User Profile Summary
The UserProfile component provides a quick summary of a player's received gifts. It shows the 10 most recent gifts and a count of how many are marked "for sale". Clicking this section navigates the user to the full GiftsPage.
Sources: components/user-profile.tsx:300-315
GiftsPage Component
This dedicated page provides a comprehensive view of all received gifts.
Key Features:
- Gift Grid: Displays all received gifts in a grid, showing the gift icon. Hovering over a gift reveals its name, sender, and date received.
- Category Filtering: Users can filter the grid by the same categories used in the
GiftShop. - "For Sale" Filter: A toggle allows users to see only the gifts they have marked for sale.
- Statistics: The page displays the total number of gifts, the number of gifts for sale, and their total calculated value.
- Actions: Buttons for "Manage Sales" and "Send Gift" provide further user actions.
Sources: components/gifts-page.tsx:88-100, components/gifts-page.tsx:180-202, components/gifts-page.tsx:156-178, components/gifts-page.tsx:282-296
Conclusion
The Gifting System is a well-integrated feature that enhances the social dynamics of the poker application. It leverages a simple data model and a series of focused React components to create a user-friendly flow for buying, sending, and managing virtual gifts. By tying into the in-game economy (chips) and social features (profiles, chat), it serves as both a monetization channel and a tool for player engagement.