minigame

Guides development of the Jackpot minigame feature across builder UI, business logic, and public play flow.

722|195|Updated Dec 9, 2024
One-click install
npx skills add https://github.com/ChatbotXIO/ChatbotX --skill minigame
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: minigame
Source: https://github.com/ChatbotXIO/ChatbotX/tree/main/.agents/skills/minigame
Command: npx skills add https://github.com/ChatbotXIO/ChatbotX --skill minigame

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The Minigame feature spans database schemas, business services, encryption tokens, and builder UI, with several unlinked code locations that silently assume only the Jackpot type works. This Skill prevents developers from missing one of the four jackpot-only gates, breaking concurrency-safe prize draws, or misusing the public play token when editing or extending the minigame system.

Core Features & Use Cases

  • Architecture Map: Locates every minigame concern, from Drizzle schema partials and prize-draw math to the public play page and jackpot preview components.
  • Trap Documentation: Catalogs nine known pitfalls, including the four-place jackpot-only enforcement, SELECT FOR UPDATE concurrency patterns, and the intentional no-redistribution behavior when prizes sell out.
  • Extension Recipe: Provides a step-by-step checklist for adding gameplay for a new minigame type (luckyWheel, gashapon, drawLots, scratchOff) without missing any gate.
  • Use Case: When asked to enable the luckyWheel minigame type, follow the recipe to update the type picker, play action gate, public page gate, and preview dispatch, then run the listed vitest suites to verify.

Quick Start

Ask the agent to add gameplay support for the luckyWheel minigame type and verify the changes with the business and encryption test suites.

Frequently Asked Questions about minigame

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new minigame type to the ChatbotX builder?

Add the type's preview, form, and play screen components, enable it in MINIGAME_TYPES_ENABLED_FOR_CREATION, update the type gates in play-minigame.action.ts and the public page, and extend MinigamePreview dispatch. Grep for every "jackpot" literal since the gates are not compiler-enforced.

Why does only the jackpot minigame type work in ChatbotX?

Jackpot-only behavior is enforced in four separate places: the type picker constant, the play action, the public page, and the preview dispatcher. The other four types (luckyWheel, gashapon, drawLots, scratchOff) are scaffolded in the schema but have no gameplay implementation.

How does the minigame play token work?

The {{minigame_play_token}} variable is minted at message-send time with a 24-hour TTL and verified on the public /minigames page. Each call site must re-check that the token's workspaceId matches the minigame's workspaceId, since no shared middleware performs this check.

What happens when a minigame prize sells out?

The draw logic filters out prizes with zero quantity but does not redistribute their win rate, so the excluded share becomes extra lose-rate. This behavior is intentional and covered by tests, so it should not be changed without reviewing resolve-minigame-prize.test.ts.

Why is there no minigame worker or queue in the codebase?

All minigame logic runs synchronously in builder server actions and pages. Outcome messages are dispatched through the pre-existing chatQueue and integrationQueue from inside recordPlayAndDispatch, sent outside the transaction so a failed send never rolls back a recorded play.