Mansion MergeAI · Claude 3.5

Core Game Loop and Mechanics

Merge Mansion is a pure construction puzzle game built around a satisfying merge-and-build loop. The player's moment-to-moment experience revolves around:

1. Purchasing base materials - Tapping the "Buy" button spawns a construction material at the lowest available grid position
2. Organizing the grid - Dragging items around to create efficient layouts and prepare for merges
3. Merging items - Dragging one item onto another of the same level to create the next tier (2-to-1 merge rule)
4. Earning cash - Each merge grants 1 cash instantly; buildings generate passive income per second
5. Strategic upgrades - Spending cash to upgrade spawn level or expand the grid

The core engagement comes from spatial puzzle-solving and economic optimization. Players must carefully manage their limited grid space while deciding when to invest in upgrades versus saving for larger purchases. The game is designed so that players never need to delete or sacrifice items - every piece has value and contributes to the final goal.

Win Condition: Successfully merge materials all the way to Level 14 (Mansion), which occupies a 3x3 space. This triggers a victory screen celebrating the player's construction achievement.

Progression Driver: The exponentially increasing costs of upgrades create natural pacing. Early game focuses on learning the merge mechanics and basic space management. Mid-game introduces the challenge of managing 2x2 buildings and optimizing passive income. Late game requires careful planning to accommodate the massive 3x3 structures while maintaining an efficient economy.

Replayability: The puzzle nature of optimal grid organization, combined with different strategic approaches to upgrade timing, makes each playthrough feel like solving an efficiency puzzle.

---

Starting Scope

The first iteration should implement a complete but streamlined version of the full game concept:

Must Have (First Iteration):

• Full 14-level merge chain from Wood Plank to Mansion
• 3x3 starting grid with expansion capability up to 7x7
• Complete spatial logic (1x1, 2x2, 3x3 item sizes)
• Transparency system for overlapped items
• Buy button spawning at lowest available tile
• Drag-and-drop merging with touch and mouse support
• Cash economy with merge rewards (1 cash per merge)
• Passive income system starting at Level 5 (Small Shed)
• Two upgrade systems: Spawn Level and Grid Expansion
• Exponential cost scaling for both upgrades
• Victory screen when Mansion is created
• Clean UI showing cash, income per second, and upgrade costs
• Edit mode allowing customization of starting cash and grid size

Can Be Added Later:

• Visual polish and particle effects for merges
• Sound effects and background music
• Tutorial or hint system
• Statistics tracking (total merges, time played, etc.)
• Additional visual themes or skins
• Save/load functionality enhancements

This scope ensures the game is fully playable, fun, and demonstrates all core mechanics while remaining achievable for the first implementation.

---

Game Perspective

2D Isometric View - The game uses a classic isometric perspective with a fixed camera angle (approximately 30-degree tilt). This provides:

• Clear visibility of all grid tiles and items
• Attractive depth and dimensionality for the construction theme
• Easy spatial understanding for drag-and-drop interactions

Camera Behavior:

• Initially fixed when grid is 3x3 to 6x6
• Once grid expands to 7 tiles in width or length, camera can pan slightly to keep all tiles accessible
• Panning should be smooth and subtle, keeping the entire grid visible when possible
• On mobile, implement touch-drag panning (separate from item dragging by detecting drag start location)
• On desktop, implement edge-of-screen panning or WASD/arrow key panning

---

Game World and Level Design

The Grid: The game takes place on a single, expandable isometric grid that serves as the construction site:

• Starting Size: 3x3 tiles
• Maximum Size: 7x7 tiles (49 total tiles)
• Expansion: Players unlock one row at a time (alternating between adding rows and columns for balanced growth)
• Visual Style: The grid should have subtle tile outlines to help with spatial awareness, with a construction site aesthetic (dirt ground, wooden planks, or similar)

Spatial Logic: The grid uses a sophisticated size system that creates interesting spatial puzzles:

• Levels 1-6 (Small Items): Occupy 1x1 grid space

  • Wood Plank, Stack of Wood, Wood Frame, Tool Shed Kit, Small Shed, Sturdy Shed

• Levels 7-12 (Medium Buildings): Occupy 2x2 grid space

  • Small Cabin, Suburban House, Cottage, Colonial House, Modern Villa, Estate Manor

• Levels 13-14 (Large Estates): Occupy 3x3 grid space

  • Grand Estate, Mansion (final goal)

Overlap and Transparency System: When a large item (2x2 or 3x3) is placed on the grid, it may cover tiles that contain other items:

• The large item becomes semi-transparent (50% opacity) to reveal items underneath
• The large item becomes un-draggable while overlapping other items
• Once the player drags away all items from underneath, the large item returns to full opacity and becomes draggable again
• This system prevents items from being "lost" under large buildings and maintains the no-delete design philosophy

Tile Positioning Logic:

• When the "Buy" button is pressed, the new item spawns at the "lowest empty tile closest to the button"
• "Lowest" means the tile with the smallest Y-coordinate in isometric space (closest to the bottom of the screen)
• If multiple tiles share the same Y-coordinate, choose the one closest to the center-bottom of the screen
• This creates predictable spawning behavior that players can plan around

---

Edit Mode Design

Edit mode allows players to customize their starting conditions and experiment with different strategies:

Editable Properties:

1. Starting Cash (default: 0)

   • Range: 0 to 10,000
   • Allows players to experiment with different economic strategies
   • Higher starting cash enables faster progression testing

2. Starting Grid Size (default: 3x3)

   • Options: 3x3, 4x4, 5x5, 6x6, 7x7
   • Lets players skip early grid expansion if desired
   • Useful for testing late-game spatial puzzles

3. Starting Spawn Level (default: 1 - Wood Plank)

   • Range: Level 1 to Level 6
   • Allows players to skip early grinding
   • Cannot start with building levels (7+) to maintain challenge

4. Passive Income Multiplier (default: 1.0x)

   • Range: 0.5x to 3.0x
   • Adjusts the speed of passive income generation
   • Enables both harder and easier economic challenges

Edit Mode UI:

• Simple sliders or number inputs for each property
• Clear labels showing current values
• "Reset to Default" button to restore original settings
• Changes take effect immediately when switching to Play mode

Constraints:

• Starting spawn level cannot exceed Level 6 (prevents trivializing the puzzle)
• Grid size cannot exceed 7x7 (technical and design limit)
• All values must be positive integers (except multiplier which is a decimal)

---

Control Design

Mobile Controls (Primary):

1. Item Dragging:

   • Touch and hold an item to pick it up
   • Drag to move it around the grid
   • Release to drop it on a tile
   • If dropped on an item of the same level, they merge
   • Visual feedback: item follows finger, slight scale increase when held

2. Buy Button:

   • Large, thumb-friendly button fixed at bottom center of screen
   • Minimum 96x96 pixels
   • Tap to spawn a new base material
   • Shows current spawn level and cost

3. Camera Panning (when grid is 7+ tiles):

   • Touch and drag on empty space (not on items) to pan camera
   • Smooth, momentum-based panning
   • Automatically centers when released
   • Distinguish from item dragging by detecting touch start location

4. Upgrade Buttons:

   • Two buttons in bottom corners or sides
   • "Upgrade Spawn" button (left side)
   • "Expand Grid" button (right side)
   • Show current cost and next level preview
   • Disabled state when insufficient cash

Desktop Controls (Secondary):

1. Item Dragging:

   • Click and hold left mouse button on an item
   • Drag to move it
   • Release to drop
   • Same merge logic as mobile

2. Buy Button:

   • Click to spawn new material
   • Keyboard shortcut: SPACE or B key

3. Camera Panning (when grid is 7+ tiles):

   • WASD or Arrow keys to pan camera
   • Or mouse-drag on empty space
   • Smooth movement with keyboard

4. Upgrade Shortcuts:

   • Q key: Upgrade Spawn Level
   • E key: Expand Grid
   • Only works when player has sufficient cash

Input Handling Requirements:

• Prevent default browser behavior for all used keys
• Clear input state on window blur
• Track touch IDs to prevent multi-touch interference
• Implement proper drag thresholds (small movements don't count as drags)
• Show visual feedback for all interactive elements (hover states, press states)

---

Economy Design

The economy is the strategic heart of Merge Mansion, creating meaningful decisions about when to upgrade versus when to save.

Cash Generation:

1. Merge Rewards:

   • Every merge of any level grants exactly 1 cash
   • Instant reward, no delay
   • Encourages active play and strategic merging

2. Passive Income:

   • Starts at Level 5 (Small Shed): 1 cash per second
   • Each building level generates income based on formula: (2 × child_income) + floor(0.15 × child_income)
   • Minimum income per building: 1 cash per second
   • Income from multiple buildings stacks additively

Passive Income Table:

• Level 5 (Small Shed): 1/sec
• Level 6 (Sturdy Shed): 2/sec
• Level 7 (Small Cabin): 4/sec
• Level 8 (Suburban House): 9/sec
• Level 9 (Cottage): 20/sec
• Level 10 (Colonial House): 46/sec
• Level 11 (Modern Villa): 105/sec
• Level 12 (Estate Manor): 241/sec
• Level 13 (Grand Estate): 553/sec
• Level 14 (Mansion): 1268/sec

Upgrade Costs:

1. Spawn Level Upgrade:

   • Starting cost: 5 cash
   • Cost formula: 5 × 5^(current_level - 1)
   • Progression: 5, 25, 125, 625, 3125, 15625
   • Upgrades the base material spawned by Buy button
   • Maximum upgrade: Level 6 (Sturdy Shed)

2. Grid Expansion:

   • Starting cost: 3 cash
   • Cost formula: 3 × 3^(expansions_purchased)
   • Progression: 3, 9, 27, 81, 243, 729, 2187, 2187, 2187, 2187, 2187, 2187, 2187, 2187, 2187, 2187
   • Each purchase adds one row or column
   • Alternates between rows and columns for balanced growth
   • Maximum expansions: 16 total (to reach 7x7 from 3x3)

Economic Balance: The exponential costs create natural pacing:

• Early game: Focus on merging and basic grid expansion
• Mid game: Balance between spawn upgrades and grid space
• Late game: Passive income becomes significant, enabling faster progression
• The 2x2 and 3x3 size requirements create spatial pressure that makes grid expansion valuable

---

Art Style and Visual Theme

Overall Style: Stylized, colorful isometric construction theme with a warm, inviting aesthetic. The art should feel like a charming construction site that gradually transforms into an elegant estate.

Visual Progression:

• Levels 1-4 (Materials): Raw wooden construction materials with visible grain and texture
• Levels 5-6 (Basic Sheds): Simple wooden structures with basic roofing
• Levels 7-12 (Houses): Increasingly sophisticated buildings with more architectural detail, windows, doors, chimneys
• Levels 13-14 (Estates): Grand, luxurious mansions with ornate details, multiple stories, gardens

Color Palette:

• Wood tones: Warm browns, tans, and honey colors for materials
• Building accents: Soft reds and grays for roofs, white/cream for walls
• Estate luxury: Rich colors like deep reds, golds, and elegant whites for final buildings
• Grid/Background: Neutral earth tones (dirt, grass, stone) that don't compete with items

Isometric Perspective:

• All assets should be rendered from the same isometric angle (approximately 30-degree tilt)
• Consistent lighting direction (top-left to bottom-right)
• Shadows should be subtle and consistent across all items

Size Consistency:

• 1x1 items: Approximately 80x80 pixels at base size
• 2x2 items: Approximately 160x160 pixels (double the 1x1 size)
• 3x3 items: Approximately 240x240 pixels (triple the 1x1 size)
• All measurements account for isometric projection

UI Style:

• Clean, modern interface with wooden texture accents
• Large, readable fonts for numbers (cash, income)
• Button designs that match the construction theme (wooden planks, tool icons)
• Subtle animations for button presses and merges

Visual Feedback:

• Merge animation: Brief flash/glow effect when two items combine
• Spawn animation: Items appear with a small "pop" effect
• Income tick: Subtle "+1" floating text when passive income generates
• Transparency effect: Smooth fade to 50% opacity for overlapped large items

---