interface ToolDefinition {
name: string;
description: string;
inputSchema: object;
handler: (args: any) => Promise<{ content: Array<{ type: 'text'; text: string }> }>;
}
const GAME_RULES_TEXT = `
Ice Puzzle Game Rules
${'='.repeat(70)}
CORE MECHANICS
--------------
The player slides on ice in a given direction until they hit an obstacle or
wall that stops them. The player cannot stop mid-slide.
TILE INTERACTIONS
-----------------
• Wall/Rock: Player stops BEFORE the tile (doesn't occupy it)
• Dirt: Player stops ON the tile (occupies it)
• Hot Coals: Player stops ON the tile and takes 5 damage on landing (20 HP total)
• Lava: Instant death if player lands on it
• Thin Ice: Player passes over it, then it breaks (one-way path)
• Warp: Player teleports to the paired warp and movement ends
• Pushable Rock: Player pushes it one square in the direction of movement,
then stops where the rock was
• Pressure Plate: Deactivates the barrier when crossed
• Barrier: Instant death if active; passable once pressure plate is crossed
HEALTH SYSTEM
-------------
• Player starts with 20 HP
• Hot Coals deal 5 damage on landing
• Standing on a hot coals tile applies additional 5 damage per second
• Player can survive 4 hot coals landings
• Lava and holes cause instant death
LEVEL DESIGN PRINCIPLES
-----------------------
1. Four Quadrant Exploration: Solutions should visit all 4 quadrants of the
grid to encourage full map exploration
2. Meaningful Choices: Each move should feel like a decision. Avoid long
corridors with only one possible direction.
3. Hidden Traps: Use lava, hot coals, and thin ice to create risk. Place them
where they're not immediately obvious from the start position.
4. Deceptive Paths: Create paths that look promising but lead to dead ends
or force backtracking. Players should discover 2+ false paths.
5. Goal Variety: Don't always put the goal in a corner. Center goals, edge
goals, and asymmetric positions create variety.
6. Direction Balance: Solutions should use all four directions relatively
evenly. Avoid solutions that are 80% horizontal or 80% vertical.
LEVEL ARCHETYPES
----------------
1. Maze: Dense walls with a dominant shortest route (ties allowed at same shortest length)
2. Gauntlet: Long path with hazards requiring precise health management
3. Hub and Spoke: Central area with paths radiating outward
4. Spiral: Path that circles inward or outward
5. Push Puzzle: Requires moving pushable rocks to create new paths
6. Key and Lock: Pressure plate unlocks barrier to reach goal
7. False Shortcut: Obvious direct path is blocked; real path is hidden
8. Bridge: Thin ice creates one-way sections that must be traversed carefully
DIFFICULTY PROGRESSION
----------------------
• Tutorial (2-6 moves): Single mechanic, obvious solution
• Easy (6-12 moves): 2 mechanics, one deceptive path
• Medium (10-17 moves): 3 mechanics, multiple deceptive paths
• Hard (14-24 moves): 4+ mechanics, quadrant exploration required
• Expert (18+ moves): All mechanics, complex interactions
DESIGN CHECKLIST
----------------
✓ Grid size: 5x5 to 25x25
✓ Start and goal positions set
✓ Level is solvable (verified by solver)
✓ Solution visits at least 3 quadrants
✓ 2+ deceptive paths exist
✓ Direction balance (no single direction >50% of moves)
✓ Meaningful mechanic usage (not just decoration)
✓ Clear visual distinction between similar tiles
`;
const TILE_TYPES_TEXT = `
Tile Types and Behaviors
${'='.repeat(70)}
BASIC TILES
-----------
ICE (default)
• Player slides across without stopping
• Most of the grid is ice
• Represented as empty space in ASCII
WALL/ROCK (#)
• Solid obstacle
• Player stops BEFORE this tile
• Creates boundaries and obstacles
• Player does NOT occupy this tile
START (S)
• Player's starting position
• Only one per level
• Must be on ice (no obstacles)
GOAL (G)
• Target position to complete level
• Only one per level
• Player must land exactly on this tile
HAZARD TILES
------------
DIRT (.)
• Slows the player
• Player stops ON this tile (occupies it)
• Safe - no damage
• Can be traversed multiple times
• Useful for creating stopping points mid-path
HOT COALS (X)
• Damage hazard
• Player stops ON this tile and takes 5 damage on landing
• Remaining on this tile applies 5 damage per second
• Player has 20 HP total, so can survive 4 hot coals landings
• Useful for creating risk/reward decisions
• Can be traversed multiple times (if HP allows)
LAVA (~)
• Instant death hazard
• If player lands on lava, they die immediately
• Creates hard barriers that must be avoided
• More punishing than hot coals
SPECIAL MECHANICS
-----------------
THIN ICE (i)
• One-way path mechanic
• Player slides over it normally the first time
• After player crosses, it breaks and becomes a hole
• If player tries to cross broken thin ice, they fall in and die
• Creates irreversible path decisions
• Multiple thin ice tiles can create complex routing puzzles
WARP (W)
• Teleportation mechanic
• Comes in pairs (each warp has a partner)
• When player slides onto a warp, they instantly teleport to its partner
• Teleporting ends movement for that move (warp-stop)
• Can create shortcuts or complex routing
• Labeled with matching IDs (W1, W2, etc.)
PUSHABLE ROCK (P)
• Interactive obstacle
• When player slides into it, the rock is pushed one square in that direction
• Player stops where the rock originally was
• If rock would be pushed into a wall/obstacle, the push fails
• Can be pushed multiple times
• Useful for creating dynamic puzzles where paths change
PRESSURE PLATE (*)
• Activation trigger
• When player crosses this tile, it activates permanently
• Typically used to deactivate a barrier
• Only one pressure plate allowed per level
• Creates key-and-lock style puzzles
BARRIER (B)
• Conditional hazard
• Starts ACTIVE (deadly)
• If player hits active barrier, instant death
• Becomes INACTIVE when pressure plate is crossed
• Only one barrier allowed per level
• Must be paired with a pressure plate
• Creates required path dependencies
TILE INTERACTION RULES
----------------------
1. Player cannot occupy same tile as wall/rock (stops before)
2. Player CAN occupy: ice, hot coals, start, goal, thin ice (before broken),
warp, pressure plate, inactive barrier
3. Player DIES on: lava, broken thin ice (hole), active barrier
4. Player takes DAMAGE on: hot coals (5 HP on landing + 5/sec while standing)
5. Player TELEPORTS on: warp (movement ends after teleport)
6. Player PUSHES: pushable rock (if space behind it is free)
7. Player STOPS on: hot coals, goal, pushable rock position (after pushing)
8. Player STOPS BEFORE: wall, rock, edge of grid
DESIGN TIPS
-----------
• Use hot coals for risk management (landing damage is 5 HP; standing is dangerous)
• Use lava as hard barriers (more severe than walls)
• Use thin ice for one-way sections and irreversible decisions
• Use warps for non-obvious routing and shortcuts
• Use pushable rocks for dynamic puzzles where environment changes
• Use pressure plate + barrier for key-and-lock challenges
• Combine mechanics for complex interactions (e.g., warp into hot coals choice)
`;
const LEVEL_REQUIREMENTS_TEXT = `
Level Requirements for Publication
${'='.repeat(70)}
MANDATORY REQUIREMENTS
----------------------
These must be satisfied or the level cannot be published:
✓ SOLVABLE
• Level must have at least one solution path from start to goal
• Verified by the BFS solver
• If unsolvable, the level is incomplete
✓ PAR / SHORTEST CORRECTNESS
• Non-tutorial levels may have tied optimal paths, but shortest optimal length must equal par
• Reject candidates where shortest optimal length is lower than par
✓ OVER-PAR FAILURE
• Timeout death rule is strict
• If move count reaches or exceeds par and the player is not on goal, run fails (WASTED)
✓ VALID GRID SIZE
• Minimum: 5x5
• Maximum: 25x25
• Larger levels require more complex solutions
✓ START AND GOAL SET
• Must have exactly one start position
• Must have exactly one goal position
• Start and goal cannot overlap
• Both must be on valid ice tiles (no obstacles)
QUALITY REQUIREMENTS
--------------------
These make levels engaging and publishable:
✓ QUADRANT EXPLORATION
• Solution should visit at least 3 of 4 quadrants
• Divide grid into quadrants at midpoint
• Encourages full map exploration
• Prevents trivial direct-line solutions
✓ DECEPTIVE PATHS
• Should have 2+ paths that look promising but are dead ends
• Creates discovery and "aha!" moments
• Makes solution non-obvious
• Use hazards, thin ice, or false shortcuts
✓ DIRECTION BALANCE
• No single direction should dominate the solution
• Target: No direction >40-50% of total moves
• Balanced directional movement feels more interesting
• Prevents "left-left-left-left-left-done" solutions
✓ MEANINGFUL MECHANICS
• Don't add mechanics as decoration
• Each special element should affect the solution path
• Pushable rocks should need to be pushed
• Warps should be used in the solution
• Pressure plates should gate progress
OPTIONAL ENHANCEMENTS
---------------------
These improve level quality but aren't required:
• THEME CONSISTENCY
• Use consistent obstacle patterns
• Create visual symmetry or patterns
• Match difficulty to move count
• HIDDEN ELEMENTS
• Place hazards in unexpected locations
• Use warps to obscure the true path
• Create false sense of safety before traps
• MULTIPLE VALID SOLUTIONS
• Some levels can have 2+ solution paths
• Creates player choice and replay value
• Harder to design but very satisfying
• PAR TIME CHALLENGE
• Set expected move count for expert players
• Usually the optimal solution length
• Creates competitive element
DIFFICULTY CALIBRATION
----------------------
Ensure your level matches its intended difficulty:
Tutorial (2-6 moves)
• Single mechanic
• Obvious solution
• No deceptive paths
Easy (6-12 moves)
• 2 mechanics
• 1-2 deceptive paths
• Simple quadrant exploration
Medium (10-17 moves)
• 3 mechanics
• 2-3 deceptive paths
• Visit 3-4 quadrants
Hard (14-24 moves)
• 4+ mechanics
• Multiple deceptive paths
• All quadrants required
• Complex interactions
Expert (18+ moves)
• All mechanics available
• Highly deceptive
• Complex mechanic interactions
• Optimal path not obvious
COMMON DESIGN MISTAKES
----------------------
✗ One long corridor (no choices)
✗ Goal in obvious direct line from start
✗ Hazards that don't affect solution
✗ Mechanics that are only decorative
✗ Solutions that only use 1-2 directions
✗ No deceptive paths (first try succeeds)
✗ Grid too small for complexity (<8x8)
✗ Grid too large for move count (>20x20 with <15 moves)
TESTING CHECKLIST
-----------------
Before publishing, verify:
□ Run solve_level tool - confirms solvable
□ Run analyze_difficulty tool - check metrics
□ Manually play through - feels fair?
□ Check for unintended shortcuts
□ Verify all mechanics are necessary
□ Confirm deceptive paths exist
□ Review direction balance
□ Ensure quadrant coverage
□ No dead-end start (4 directions blocked)
□ Goal is reachable from multiple directions
`;
export function getGameRulesTools(): ToolDefinition[] {
return [
{
name: 'get_game_rules',
description: 'Get comprehensive game rules covering mechanics, design principles, and level archetypes',
inputSchema: {
type: 'object',
properties: {}
},
handler: async () => {
return {
content: [{
type: 'text',
text: GAME_RULES_TEXT
}]
};
}
},
{
name: 'get_tile_types',
description: 'Get detailed information about all tile types and their behaviors',
inputSchema: {
type: 'object',
properties: {}
},
handler: async () => {
return {
content: [{
type: 'text',
text: TILE_TYPES_TEXT
}]
};
}
},
{
name: 'get_level_requirements',
description: 'Get requirements and best practices for creating publishable levels',
inputSchema: {
type: 'object',
properties: {}
},
handler: async () => {
return {
content: [{
type: 'text',
text: LEVEL_REQUIREMENTS_TEXT
}]
};
}
}
];
}
