Building an Escape Room Puzzle Designer in typescript with NodeJS

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.

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. Escape room designers face several challenges: Our agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered puzzle search, and intelligent difficulty balancing. The Escape Room Puzzle Designer uses a multi-agent architecture where each agent specializes in a specific aspect of puzzle design: This separation allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them. One 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: When 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. The RAG implementation uses HazelJS's RAGPipeline with a MemoryVectorStore for efficient semantic search: @Service export class PuzzleKnowledgeBaseService { private readonly embeddings = new LocalPuzzleEmbeddingProvider ; private readonly vectorStore = new MemoryVectorStore this.embeddings ; private readonly rag = new RAGPipeline { vectorStore: this.vectorStore, embeddingProvider: this.embeddings, topK: 3, } ; async answer query: string, topK = 3 { const sources = await this.search query, topK ; return { answer: sources.map source = source.content .join '\n\n' , sources: sources.map source = { id: source.id, score: Number source.score.toFixed 3 , type: source.metadata?.type, difficulty: source.metadata?.difficulty, theme: source.metadata?.theme, estimatedTime: source.metadata?.estimatedTime, } , }; } } The DifficultyBalancerAgent takes a puzzle and adjusts its parameters to match target difficulty and time constraints. It considers: The 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. The HintProviderAgent implements a progressive hint system that guides players without spoiling the solution. It provides: This progressive approach ensures that players get the right level of help at the right time, maintaining the challenge while preventing frustration. The SolutionTrackerAgent verifies player solutions using similarity scoring. It: The agent maintains solution history for each puzzle, allowing designers to analyze which puzzles are too easy or too difficult based on player performance data. The 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: The supervisor continues delegating until it has gathered enough information to provide a comprehensive puzzle package, then synthesizes the results into a cohesive puzzle design. Despite being a demo, the agent includes production-ready features: The agent can be run with: npm install npm run build npm run dev The app runs on http://localhost:3000 with the HazelJS Inspector available at / hazel for real-time monitoring and debugging. You can test the agent with a curl request: curl -s -X POST http://localhost:3000/puzzle/supervisor \ -H 'content-type: application/json' \ -d '{"message":"Design a logic puzzle with detective theme, medium difficulty, 10 minutes. Balance the difficulty and provide hints.","userId":"puzzle-designer-1"}' The 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. Complete Project: Escape Room Puzzle Designer https://github.com/nisafatimaa/escape-room-puzzle-designer HazelJS Documentation: Docs https://hazeljs.ai/docs The Escape Room Puzzle Designer demonstrates several key HazelJS capabilities: This 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.