{"slug": "building-an-escape-room-puzzle-designer-in-typescript-with-nodejs", "title": "Building an Escape Room Puzzle Designer in typescript with NodeJS", "summary": "A developer built an Escape Room Puzzle Designer using HazelJS, a multi-agent framework, to help designers create balanced puzzles with progressive hints and solution tracking. The system uses a RAG pipeline for semantic puzzle search and a DifficultyBalancerAgent to adjust puzzle parameters, while a SupervisorAgent coordinates specialist agents for comprehensive puzzle design.", "body_md": "Escape rooms have become increasingly popular as interactive entertainment experiences. The key to a great escape room lies in its puzzles—they need to be challenging enough to be engaging, but not so difficult that players become frustrated. In this post, we'll build an Escape Room Puzzle Designer using [HazelJS](https://hazeljs.ai/) that helps create balanced puzzles, provide progressive hints, and track player solutions.\n\nEscape room designers face several challenges:\n\nOur agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered puzzle search, and intelligent difficulty balancing.\n\nThe Escape Room Puzzle Designer uses a multi-agent architecture where each agent specializes in a specific aspect of puzzle design:\n\nThis separation allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them.\n\nOne of the key features of our agent is the ability to search through a database of puzzles using Retrieval-Augmented Generation (RAG). We maintain a knowledge base of puzzles with metadata including:\n\nWhen a designer asks about puzzles, the PuzzleDesignerAgent uses semantic search to find relevant puzzles based on their query. For example, a query like \"Find logic puzzles with detective theme\" would return puzzles matching those criteria.\n\nThe RAG implementation uses HazelJS's `RAGPipeline`\n\nwith a `MemoryVectorStore`\n\nfor efficient semantic search:\n\n```\n@Service()\nexport class PuzzleKnowledgeBaseService {\n  private readonly embeddings = new LocalPuzzleEmbeddingProvider();\n  private readonly vectorStore = new MemoryVectorStore(this.embeddings);\n  private readonly rag = new RAGPipeline({\n    vectorStore: this.vectorStore,\n    embeddingProvider: this.embeddings,\n    topK: 3,\n  });\n\n  async answer(query: string, topK = 3) {\n    const sources = await this.search(query, topK);\n    return {\n      answer: sources.map((source) => source.content).join('\\n\\n'),\n      sources: sources.map((source) => ({\n        id: source.id,\n        score: Number(source.score.toFixed(3)),\n        type: source.metadata?.type,\n        difficulty: source.metadata?.difficulty,\n        theme: source.metadata?.theme,\n        estimatedTime: source.metadata?.estimatedTime,\n      })),\n    };\n  }\n}\n```\n\nThe DifficultyBalancerAgent takes a puzzle and adjusts its parameters to match target difficulty and time constraints. It considers:\n\nThe balancer provides detailed analysis including difficulty adjustment recommendations, time adjustment suggestions, and complexity descriptions. This helps designers create puzzles that are appropriately challenging for their target audience.\n\nThe HintProviderAgent implements a progressive hint system that guides players without spoiling the solution. It provides:\n\nThis progressive approach ensures that players get the right level of help at the right time, maintaining the challenge while preventing frustration.\n\nThe SolutionTrackerAgent verifies player solutions using similarity scoring. It:\n\nThe agent maintains solution history for each puzzle, allowing designers to analyze which puzzles are too easy or too difficult based on player performance data.\n\nThe PuzzleManagerAgent uses HazelJS's supervisor routing to coordinate between the specialist agents. When a designer makes a request, the supervisor analyzes the request and routes it to the appropriate specialist:\n\nThe supervisor continues delegating until it has gathered enough information to provide a comprehensive puzzle package, then synthesizes the results into a cohesive puzzle design.\n\nDespite being a demo, the agent includes production-ready features:\n\nThe agent can be run with:\n\n```\nnpm install\nnpm run build\nnpm run dev\n```\n\nThe app runs on `http://localhost:3000`\n\nwith the HazelJS Inspector available at `/__hazel`\n\nfor real-time monitoring and debugging.\n\nYou can test the agent with a curl request:\n\n```\ncurl -s -X POST http://localhost:3000/puzzle/supervisor \\\n  -H 'content-type: application/json' \\\n  -d '{\"message\":\"Design a logic puzzle with detective theme, medium difficulty, 10 minutes. Balance the difficulty and provide hints.\",\"userId\":\"puzzle-designer-1\"}'\n```\n\nThe agent will analyze your request, design a puzzle, balance its difficulty, provide progressive hints, and set up solution tracking—all coordinated through the supervisor routing system.\n\nComplete Project: [Escape Room Puzzle Designer](https://github.com/nisafatimaa/escape-room-puzzle-designer)\n\nHazelJS Documentation: [Docs](https://hazeljs.ai/docs)\n\nThe Escape Room Puzzle Designer demonstrates several key HazelJS capabilities:\n\nThis agent shows how [HazelJS](https://hazeljs.ai/) can be used to build fun, engaging applications that solve complex creative challenges while maintaining production-grade quality and reliability. The multi-agent approach makes it easy to extend the system with additional specialists (like theme generators or narrative designers) as needed.", "url": "https://wpnews.pro/news/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs", "canonical_source": "https://dev.to/nisa_fatima_bcd75fa085b76/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs-2lm8", "published_at": "2026-07-29 17:33:20+00:00", "updated_at": "2026-07-29 18:02:39.865386+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "machine-learning", "natural-language-processing"], "entities": ["HazelJS", "PuzzleDesignerAgent", "DifficultyBalancerAgent", "HintProviderAgent", "SolutionTrackerAgent", "PuzzleManagerAgent", "RAGPipeline", "MemoryVectorStore"], "alternates": {"html": "https://wpnews.pro/news/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs", "markdown": "https://wpnews.pro/news/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs.md", "text": "https://wpnews.pro/news/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs.txt", "jsonld": "https://wpnews.pro/news/building-an-escape-room-puzzle-designer-in-typescript-with-nodejs.jsonld"}}