Turn real-world locations into playable AI-powered quests, escape rooms, and social adventures.
QuestScape is a location-based adventure platform where users can search for a place, play an existing community quest, or generate a brand-new personalised quest using AI.
Each quest can include storylines, role-play, physical checkpoints, puzzles, clues, language-learning activities, and a final escape-room challenge. Generated quests are stored in Supabase so they can be replayed, shared, upvoted, and improved by the community.
QuestScape combines:
- Google Maps for location search and discovery
- DeepSeek AI for quest generation, role design, puzzle creation, and validation
- Supabase for authentication, quest storage, play history, voting, and community data
The first product vertical focuses on Chinese-learning adventures, where users practise Chinese through real-world exploration, role-play, cultural discovery, and cooperative puzzle solving.
Search a place. Choose an adventure. Step into a new role.
Users can:
- Search by place name
- Browse quests on a map
- Find quests near their current location
- Filter by group type, difficulty, language, duration, and quest style
- Open directions in Google Maps
Existing quests are stored and reused without regeneration.
Users can:
- Browse quests attached to a location
- View duration, difficulty, player count, and language level
- Start a stored quest immediately
- Save quests for later
- Upvote quests after playing
- Report inaccurate or broken content
Users can generate a personalised quest based on:
- Location
- Solo or group play
- Number of players
- Age range
- Preferred language
- Chinese proficiency
- Duration
- Difficulty
- Story theme
- Walking distance
- Accessibility needs
The generated quest is validated, stored in Supabase, and can be played immediately.
Each player receives a different role, such as:
- Detective
- Navigator
- Linguist
- Code Breaker
- Historian
- Negotiator
- Guardian
- Storyteller
Roles affect what each player can see, know, or do during the quest.
A QuestScape adventure is not just a list of questions.
Each quest follows a connected structure:
Story introduction
↓
Role assignment
↓
Checkpoint puzzles
↓
Collected clues
↓
Final meta-puzzle
↓
Story conclusion and reward
The final puzzle uses clues collected earlier in the adventure.
Chinese is integrated into gameplay through:
- Speaking challenges
- Character matching
- Vocabulary clues
- Role-play conversations
- Cultural puzzles
- Story-building tasks
- Direction and observation activities
The goal is practical communication rather than strict examination.
Search a location
↓
Open the location page
↓
Choose:
- Play an existing quest
- Create a new quest
↓
Complete checkpoints and puzzles
↓
Solve the final challenge
↓
Save, upvote, share, or report
QuestScape uses a controlled multi-stage AI workflow rather than a single prompt.
Searches Supabase for existing quests matching the user's:
- Location
- Group size
- Duration
- Language
- Difficulty
- Previous play history
Loads approved location and checkpoint information before generation.
The AI should not invent places, objects, or landmarks that are not present in the location data.
Creates:
- Story premise
- Objective
- Tone
- Quest structure
- Learning objective
- Ending
Assigns meaningful roles based on player count, age, ability, and previous role history.
Creates a connected puzzle graph using approved puzzle templates.
Adjusts Chinese content based on the selected proficiency level.
Checks:
- Checkpoint validity
- Puzzle solvability
- Role participation
- Final clue dependencies
- Duration
- Difficulty
- Safety
- Repetition
Regenerates only failed sections instead of replacing the entire quest.
Provides progressive hints and story-based support during play.
Uses completion data, upvotes, reports, and recent play activity to improve quest recommendations.
The hackathon MVP focuses on one location: Chinatown.
-
The Vanishing Lantern
A Chinese-learning time-travel mystery. -
The Secret Menu
A food and language treasure hunt.
- Search for Chinatown
- View stored quests
- Start an existing quest without regeneration
- Assign player roles
- Complete three checkpoints
- Solve the final puzzle
- Upvote the quest
- Generate a new custom quest
- Save the generated quest in Supabase
- Display the new quest on the location page
- Frontend: Web or mobile frontend
- Backend: Supabase
- Database: PostgreSQL through Supabase
- Authentication: Supabase Auth
- AI: DeepSeek API
- Maps: Google Maps Platform
- Server-side AI calls: Supabase Edge Functions
- Realtime: Supabase Realtime, planned for multiplayer
- Storage: Supabase Storage, planned for images and quest media
The repository may use a structure similar to:
QuestScape/
├── design/
├── docs/
│ └── superpowers/
├── questscape/
│ ├── src/
│ ├── public/
│ ├── components/
│ ├── services/
│ └── pages/
├── supabase/
│ ├── functions/
│ ├── migrations/
│ └── seed.sql
├── .gitignore
└── README.md
Update this section to match the final application structure.
Create a local environment file based on your framework, for example:
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_keyStore the DeepSeek key only in a secure server-side environment:
DEEPSEEK_API_KEY=your_deepseek_api_key- Never expose the DeepSeek API key in the frontend
- Never expose the Supabase service-role key in the frontend
- Call DeepSeek through a Supabase Edge Function
- Enable Row Level Security on all exposed tables
- Use user ownership checks for private quests, votes, and play history
Create a Supabase project and configure:
- Authentication
- Database tables
- Row Level Security
- Edge Functions
- Environment secrets
profiles
locations
location_checkpoints
quests
quest_roles
quest_checkpoints
quest_puzzles
quest_plays
quest_votes
quest_reports
saved_quests
quest_generation_runs
A generated quest is stored as a fixed version.
Opening a quest must not regenerate it.
If a creator changes or regenerates a quest, create a new version so existing ratings and play history remain attached to the correct quest version.
Enable the required Google Maps APIs for the application, such as:
- Maps JavaScript API
- Places API
- Geocoding API, where required
For the MVP:
- Show location pins
- Search for a place
- Display quest locations
- Provide an external Google Maps directions link
Full live route navigation and GPS checkpoint validation can be added later.
DeepSeek should return structured JSON rather than unstructured text.
Example quest response:
{
"title": "The Vanishing Lantern",
"story_type": "time_travel_mystery",
"summary": "Recover four lost memories before the lantern disappears.",
"difficulty": "medium",
"estimated_minutes": 45,
"roles": [],
"checkpoints": [],
"final_puzzle": {}
}Validate the response before saving it.
Minimum checks:
- Title exists
- Approved checkpoint IDs are used
- Roles are present
- Puzzles are present
- Final puzzle uses earlier clues
- Duration is within the selected range
- Language level matches the request
Quests can use the following visibility levels:
- Private — only the creator can access
- Unlisted — accessible through a direct link or code
- Public — visible in location search after validation
- Official — verified by an attraction, educator, or partner
Recommended lifecycle:
Generated
→ Validated
→ Private Playtest
→ Creator Confirmed
→ Public
→ Community Tested
→ Verified or Official
After playing, users can:
- Recommend the quest
- Save it
- Share it
- Report an issue
- Provide structured feedback
Suggested feedback categories:
- Story was engaging
- Puzzles were clear
- Location clues were accurate
- Difficulty was suitable
- Chinese level was suitable
- Duration estimate was accurate
Quest ranking should consider more than raw upvotes.
Recommended ranking signals:
- Upvote rate
- Completion rate
- Recent successful plays
- Low report rate
- Location accuracy
- Difficulty accuracy
- Freshness
- Group suitability
Install dependencies inside the application directory.
Example:
cd questscape
npm install
npm run devUse the commands defined in the project's package.json if they differ.
- Map and location search
- One supported location
- Two stored quests
- Existing quest play flow
- Role assignment
- Three puzzle checkpoints
- Final connected puzzle
- Upvote flow
- New quest generation
- Quest validation
- Supabase storage
- Full multi-device multiplayer
- Live GPS navigation
- Computer-vision verification
- Speech grading
- Payment processing
- Public creator marketplace
- Partner dashboard
- Full moderation system
- City-wide location coverage
- One location
- Existing quests
- Custom quest generation
- Supabase storage
- Basic upvoting
- More supported locations
- User profiles
- Saved quests
- Reports
- Solo and group modes
- Improved validation
- Public quest creation
- Creator profiles
- Quest versioning
- Trending quests
- Community-tested badges
- Personalised recommendations
- Official attraction quests
- Educator tools
- Visitor analytics
- Seasonal campaigns
- Branded experiences
- Live Game Master
- Automated quest repair
- Multi-device private clues
- Voice role-play
- Dynamic route adaptation
- Computer-vision clue validation
Possible future revenue streams include:
- Premium subscriptions
- AI quest-generation credits
- Individual premium quest purchases
- Attraction partnerships
- School and enrichment packages
- Corporate team-building quests
- Creator marketplace commissions
- Sponsored seasonal adventures
The MVP is successful when a user can:
- Search for a supported location
- Browse existing quests
- Start a stored quest without regeneration
- Understand the role system
- Complete checkpoint puzzles
- Solve the final connected challenge
- Upvote the quest
- Generate a new personalised quest
- Save the generated quest in Supabase
- See it appear in the location catalogue
QuestScape is currently in early development.
Before submitting changes:
- Keep quests grounded in approved location data
- Preserve fixed quest versions
- Do not expose private API keys
- Add validation for AI-generated output
- Test existing and generated quest flows
- Follow the project's coding and documentation standards
Add the selected project licence here.
For example:
MIT License
QuestScape is currently a hackathon MVP and proof of concept.
The project is being developed to validate:
- Location-based quest discovery
- Reusable community quests
- AI-generated custom adventures
- Agentic quest validation
- Chinese-learning gameplay
- Community rating and storage