Coin CrazeAI · Claude 3.5

Core Game Loop and Mechanics

Moment-to-Moment Gameplay: The player looks at a physical coin tray with 15 slots arranged in a 3x5 grid. Each slot is a deep rectangular well that holds coins stacked on their edge (like a coin roll lying on its side). The front coin in each slot shows its tier number clearly, with additional coins visible receding into the slot depth.

The core loop consists of:

1. Deal Phase: Press the Deal button to receive a batch of coin stacks that drop into random unlocked slots
2. Sort Phase: Drag same-tier coin groups from the front of slots to reorganize and set up merges
3. Merge Phase: When any slot reaches exactly 10 coins of the same tier, they automatically collapse into 2 coins of the next tier
4. Chain Reactions: Merges can trigger additional merges, multiplying score with each chain step

Progression:

• Start with only the bottom row (5 slots) unlocked
• Every 5 merges triggers a level up, unlocking one additional slot
• Early levels deal only Bronze (1) and Silver (2) coins
• Mid levels introduce Gold (3) and Blue (4)
• Later levels deal the full tier range up to Red (7) and beyond
• Difficulty increases as more slots unlock and higher tiers appear

Win/Lose Conditions:

• Game Over: Occurs when all unlocked slots are completely full (10 coins each) and the player presses Deal with no possible merges
• Endless Progression: No traditional "win" - the game continues as long as the player can manage space and create merges
• High Score Chase: Players aim to maximize score through strategic sorting and chain reactions

Engagement Drivers:

• Spatial Puzzle: Managing limited slot space creates constant tension
• Chain Reaction Satisfaction: Setting up multi-step merges for exponential score bonuses
• Progression Unlocks: New slots open up strategic possibilities
• Risk/Reward: Deciding when to deal vs. when to sort more
• Visual Feedback: Satisfying merge animations and coin physics

Starting Scope

First Iteration Must Include:

• Complete 3x5 slot tray with proper 3D perspective view
• Coin stacking system with front-to-back depth visualization
• 7 tier system (Bronze through Red) with distinct colors and numbers
• Drag-and-drop mechanics for same-tier groups from slot fronts
• Automatic merge detection and execution (10 → 2 of next tier)
• Chain merge detection with score multipliers
• Deal system that drops coin batches into random unlocked slots
• Progressive slot unlocking (start with 5, unlock 1 per level)
• Level progression (every 5 merges)
• Tier distribution that scales with level
• Game over detection
• HUD with score, level, progress bar, and Deal button
• Drop animations with bounce
• Play Again functionality

Polish Elements for First Iteration:

• Smooth drag feedback with lifted coin group following pointer
• Merge animation (coins collapsing and transforming)
• Slot unlock animation with padlock
• Coin drop physics with bounce
• Metallic material rendering for coins
• Clear tier numbers on coin faces
• Visual distinction between locked/unlocked slots

Future Enhancements (Not in First Iteration):

• Sound effects for deals, merges, drops
• Particle effects for chain reactions
• Additional tier colors beyond 7
• Tutorial overlay for first-time players
• Statistics tracking (best chain, highest tier reached)
• Undo functionality
• Hint system

Game Perspective

3D Third-Person Fixed Camera

The game uses a fixed 3D perspective camera positioned slightly above and in front of the coin tray, looking down at approximately 20-30 degrees. This angle is critical for:

• Clear visibility of the tier number on the front coin face in each slot
• Readable depth perception showing coins receding into each slot
• Understanding the 3-row layout (bottom row nearest, top row furthest)
• Maintaining the physical "shelf of coin rolls" metaphor

The camera never moves during gameplay, providing a stable reference frame for the spatial puzzle.

Game World and Level Design

The Coin Tray:

• Physical dimensions: Approximately 5 units wide × 3 units tall in 3D space
• Material: Light grey or warm white plastic with subtle sheen
• 15 rectangular slot wells arranged in a 3×5 grid
• Each slot is a deep rectangular cavity (approximately 0.8 units wide × 0.3 units tall × 2 units deep)
• Slots have visible inner walls to show depth
• Small gaps between slots for visual separation

Slot Layout:

[Top Row - Slots 11-15]    [Furthest from viewer]
[Middle Row - Slots 6-10]  [Middle distance]
[Bottom Row - Slots 1-5]   [Closest to viewer]

Slot States:

• Unlocked: Normal appearance, can receive coins, shows current coin stack
• Locked: Shows padlock icon, greyed out, cannot receive coins
• Full: Contains 10 coins (maximum capacity)

Coin Stacking System: Each slot holds 0-10 coins stacked front-to-back:

• Coins are positioned along the Z-axis (depth) of the slot
• Front-most coin is fully visible with tier number facing viewer
• Subsequent coins are positioned behind, slightly visible as receding edges
• Spacing: approximately 0.18 units between coin centers
• When full, 10 coins fill the slot depth from front to back

Tier System:

Tier	Color	Number	Material
1	Bronze	1	Metallic copper/bronze
2	Silver	2	Metallic silver
3	Gold	3	Metallic gold
4	Blue	4	Metallic blue
5	Green	5	Metallic green
6	Purple	6	Metallic purple
7	Red	7	Metallic red
8+	Extended palette	8+	Additional metallic colors

Level Progression:

Level 1-2 (5 slots unlocked - bottom row):

• Deal: 2-3 stacks per deal
• Tiers: 80% tier 1, 20% tier 2
• Stack size: 1-4 coins

Level 3-5 (6-8 slots unlocked - filling middle row):

• Deal: 3-4 stacks per deal
• Tiers: 50% tier 1, 30% tier 2, 20% tier 3
• Stack size: 1-5 coins

Level 6-9 (9-12 slots unlocked - completing middle row, starting top row):

• Deal: 4-5 stacks per deal
• Tiers: 30% tier 1, 30% tier 2, 25% tier 3, 15% tier 4
• Stack size: 2-5 coins

Level 10+ (13-15 slots unlocked - completing top row):

• Deal: 5-7 stacks per deal
• Tiers: 20% tier 1, 20% tier 2, 20% tier 3, 20% tier 4, 10% tier 5, 10% tier 6+
• Stack size: 2-6 coins

Unlock Sequence: Slots unlock in this order: 1→2→3→4→5 (bottom row) → 6→7→8→9→10 (middle row) → 11→12→13→14→15 (top row)

Edit Mode Design

Editable Properties:

Tier Colors:

• Each tier (1-7+) has an editable color value
• Users can customize the metallic color of coins for each tier
• Constraint: Colors must be distinct enough to differentiate tiers

Tier Count:

• Number of tiers available in the game (minimum 4, maximum 10)
• Higher tier counts increase late-game complexity

Merge Threshold:

• Number of coins required to trigger a merge (default: 10)
• Range: 5-15 coins
• Affects difficulty and pacing

Deal Batch Size:

• Multiplier for number of stacks dealt per deal (default: 1.0)
• Range: 0.5-2.0
• Lower values = more strategic, higher values = more chaotic

Level Up Frequency:

• Number of merges required per level (default: 5)
• Range: 3-10 merges
• Affects unlock pacing

Starting Slots:

• Number of slots unlocked at game start (default: 5)
• Range: 3-10 slots
• More slots = easier start

Slot Capacity:

• Maximum coins per slot (default: 10)
• Range: 8-15 coins
• Affects merge timing and space management

Score Multiplier:

• Base score multiplier (default: 100)
• Range: 50-500
• Affects score scaling

Implementation: All editable values stored in window.gameConfig object with the following structure:

window.gameConfig = {
  tierColors: ['#CD7F32', '#C0C0C0', '#FFD700', '#4169E1', '#32CD32', '#9370DB', '#DC143C'],
  tierCount: 7,
  mergeThreshold: 10,
  dealBatchMultiplier: 1.0,
  levelUpFrequency: 5,
  startingSlots: 5,
  slotCapacity: 10,
  scoreMultiplier: 100
};

Control Design

Desktop Controls:

• Mouse Click + Drag: Click and hold on the front coin(s) of a slot to lift the same-tier group, drag to destination slot, release to drop
• Mouse Click on Deal Button: Triggers new coin batch
• Mouse Click on Play Again: Restarts game after game over

Mobile Controls:

• Touch + Drag: Touch and hold on the front coin(s) of a slot to lift the same-tier group, drag to destination slot, release to drop
• Tap on Deal Button: Triggers new coin batch
• Tap on Play Again: Restarts game after game over

Drag Mechanics Details:

1. Drag Initiation:

   • Raycast from pointer position to detect which slot was clicked/touched
   • Identify the front-most coin tier in that slot
   • Count consecutive coins of the same tier from the front
   • Lift this entire group as a single unit

2. During Drag:

   • Lifted coin group follows pointer position in 3D space
   • Group hovers slightly above the tray (elevated Y position)
   • Visual feedback: lifted coins slightly enlarged or glowing
   • Raycast continuously to detect which slot is under the pointer
   • Highlight valid drop target slots

3. Drop:

   • On pointer release, raycast to determine destination slot
   • If over a valid unlocked slot: animate coins dropping into that slot's front position
   • If over invalid target (locked slot, original slot, or empty space): animate coins returning to original position
   • After drop, immediately check for merge conditions

Input State Management:

• Track pointer down/up events
• Store drag state (isDragging, draggedCoins, sourceSlot)
• Clear input state on window blur
• Prevent default touch behaviors to avoid scrolling during drag

Pointer Lock: Not required for this game

Virtual Controls: None needed - direct manipulation only

Art Style and Visual Theme

Overall Style: Clean 3D Realism with Game Polish

The game uses a realistic 3D rendering style with polished materials and lighting, evoking the tactile feel of physical coins and a quality coin sorting tray. The aesthetic is clean, professional, and satisfying to interact with.

Color Palette:

• Tray: Light grey (#E8E8E8) or warm white (#F5F5DC) plastic with subtle sheen
• Tier Colors: Distinct metallic colors that are easily distinguishable
  • Bronze: #CD7F32 (copper/bronze metallic)
  • Silver: #C0C0C0 (bright silver metallic)
  • Gold: #FFD700 (rich gold metallic)
  • Blue: #4169E1 (royal blue metallic)
  • Green: #32CD32 (lime green metallic)
  • Purple: #9370DB (medium purple metallic)
  • Red: #DC143C (crimson metallic)
• Locked Slots: Desaturated grey (#999999) with padlock icon
• UI: Dark grey (#333333) text on semi-transparent white backgrounds

Coin Design:

• Geometry: CylinderGeometry (radius: 0.12 units, height: 0.04 units, 32 segments)
• Material: MeshStandardMaterial with metallic: 0.8, roughness: 0.3
• Orientation: Rotated 90° so flat faces point toward viewer (left/right)
• Tier Number: Bold white text on the front flat face, generated via CanvasTexture
  • Font: Bold sans-serif, size proportional to coin face
  • Centered on the circular face
  • High contrast for readability

Tray and Slot Design:

• Tray Base: BoxGeometry with rounded edges (if possible via custom geometry)
• Slot Wells: BoxGeometry carved into the tray, showing inner walls
• Slot Dimensions: 0.8 units wide × 0.3 units tall × 2 units deep
• Inner Walls: Slightly darker shade than tray base for depth perception
• Gaps: 0.1 unit spacing between slots

Lighting:

• Ambient Light: Soft white (#FFFFFF) at intensity 0.4 for overall illumination
• Directional Light: White (#FFFFFF) at intensity 0.8, positioned above and slightly in front of the tray (casting subtle shadows)
• Shadow Rendering: Optional but recommended for depth - coins cast subtle shadows on slot walls

Camera Setup:

• Type: PerspectiveCamera
• FOV: 50-60 degrees
• Position: Approximately (0, 4, 6) in world space
• LookAt: Center of the tray (0, 0, 0)
• Angle: 20-30 degrees downward tilt for optimal slot visibility

Animation Style:

• Coin Drops: Smooth fall with slight bounce on landing (ease-out curve)
• Merge Animation: Coins scale down and fade, new coins scale up from center
• Drag: Smooth follow with slight lag for natural feel
• Unlock: Padlock fades out, slot brightens with subtle pulse

UI Style:

• HUD: HTML/CSS overlay with clean typography
• Font: Sans-serif (Arial, Helvetica, or system font)
• Deal Button: Large, prominent, rounded rectangle with gradient
• Progress Bar: Thin horizontal bar with smooth fill animation
• Score/Level: Clear, bold numbers with subtle drop shadow

Asset vs. Code Rendering:

• Code-Rendered: Tray, slots, coins (Three.js geometries and materials), all UI elements
• Generated Assets: Padlock icon for locked slots

Consistency Notes:

• All coins use the same geometry and material system, differentiated only by color and number texture
• Metallic finish is consistent across all tiers
• Lighting setup remains constant throughout gameplay
• UI maintains consistent spacing and typography