Puzzlehunt creator guide

Read this section before submitting. The following guidelines apply to all Hunt content and operational conduct, and relate to platform review, takedown, and account actions.

Simultaneous submission & cross-platform publishing

• This site supports simultaneous submission: you may publish the same puzzle event on this platform and other platforms at the same time.
• Before simultaneous submission, confirm whether other platforms allow cross-site publishing to avoid copyright disputes or other unnecessary issues.
• If other platforms require first publication, exclusivity, or restrict republishing, comply on your own; this site does not guarantee your agreements with other platforms.

Re-run Hunts

• This site encourages uploading re-run Hunts (previously held events relaunched on this site). Check Mark as re-run Hunt under Basics.
• You can fill in original link and original publish date; the player-facing UI shows a Re-run label and source information so new and returning players can tell them apart.
• Do not mislabel a re-run Hunt as a brand-new first release; if puzzles, rules, or the schedule changed substantially, note the differences in the summary or FAQ.

Copyright & licensing

• Ensure you have lawful rights or authorization for uploaded puzzle text, images, audio, interactive packages, map assets, and similar content; do not infringe copyright, trademarks, portrait rights, or other lawful interests.
• For team co-creation, agree on credits and rights with members in advance, and fill in lead creators and puzzle authors correctly in the Hunt.
• When using third-party assets (fonts, music, film screenshots, brand elements, etc.), confirm the license allows public event use and long-term online display.

Legal compliance

• Submitted content and how you run the event must follow applicable law.
• You are responsible for compliance in every country or region where you operate.
• If a Hunt targets players in specific places, also assess local rules on online events, raffles, minors, and data collection.

Content safety & player experience

• Do not publish illegal content, violence incitement, hate speech, harassment, fraud, malicious code, or content clearly unsuitable for public events.
• Do not publish horror, gore, adult-oriented themes, or similar material.
• Do not use puzzle text, assets, or interactive packages to bypass platform answer and hint protection, or leak key information before unlock or hint purchase.
• Complete self-testing and testsolver coverage before publishing; during the event, fix fairness or playability issues promptly via announcements and errata.

Data & privacy

• If the Hunt collects registration emails, contact information, or other personal data, use it only for event communication and necessary operations, and comply with applicable privacy and data protection rules.
• Do not publicly require players to submit passwords, full ID numbers, bank card information, or other sensitive data in puzzle text, rules, or announcements.

Platform review

• Content violating these guidelines may be required to be modified, delayed, or taken down; serious or repeated violations may restrict creator permissions.
• If you have questions about review conclusions, contact the platform via Hunt contact information or in-site feedback channels.

Fill in the fields under Basics in the Hunt editor for public display and schedule:

• Title: Main title on list and detail pages.
• Custom URL path (slug): Used for custom links (e.g. https://puzzle.cat/hunt/summer-2026; default ID links stay /hunts/{id}). Lowercase letters, digits, and hyphens only; at least 4 characters; leave blank to auto-generate from the title.
• Summary: Hunt list and detail blurb.
• Tags: Separate multiple tags with commas for player search.
• Contact / FAQ / Rules: Shown on the Hunt detail page for participants.
• Start / end time: Together with timezone, drives Upcoming, In progress, and Ended; timed unlock rules depend on the schedule.
• Hunt type: Standard events require an end time; Evergreen Hunts have no end time, stay open after start, and in-event registration cannot be disabled by default.
• Visibility: public visible in public lists; unlisted link-only; private requires permission.
• Re-run Hunt: When checked, you can fill original link and original publish date (see Guidelines).
• Timezone: Affects leaderboard time display and timeAfterStart-style unlock rules.
• Affiliated creator team: Optionally bind a long-term team; members do not automatically get edit access—grant it separately under Co-create.
• Submit to platform event: Link this Hunt to an active platform event for event-page display and points (if the event accepts submissions).

For multi-person collaboration, bind a creator team and configure co-create permissions within the Hunt:

• Creator teams: Long-term organizations whose members can be reused across Hunts; when creating a Hunt you can preselect a team and batch-add initial authors.
• My Hunts → Co-create: Add roles such as lead organizer, collaborator, section lead, staff, and testsolver for a single Hunt.
• staff can access the ops dashboard, announcement errata, and manual hint queue; testsolver can only playtest and cannot edit drafts.
• Public lead credits appear on the Hunt detail page; each puzzle can also list puzzle authors separately (see Credits).

The Visual & banner section controls player-facing puzzle-map and puzzle-page styling:

• Apply primary, accent, background, and corner radius from presets (e.g. neon-dark) in one click.
• Background mode: Solid, gradient, or image; banner images are used on list cards and the detail header.
• Card opacity / border glow: Tune puzzle-card readability over the background.
• Upload background images via the asset library and reference them—avoid uncontrolled external domains.

The puzzle map is built from sections and puzzles:

• Sections can nest for meta regions and chapter-style layouts; each section can set width (column count) and map position.
• The puzzle list table supports inline editing in collapsed rows: title, section, type, points, unlock summary, hint count.
• The map editor lets you drag puzzles within a section and set a custom background as the section base map.
• Puzzle IDs must stay stable within the structure; unlock rules, wrap-up, and ratings all reference them—do not rename published puzzles casually.

In the Puzzles section, switch to visual mode (or use ?mode=visual in the edit URL):

• A React Flow canvas shows puzzle nodes and unlock edges; drag nodes to adjust layout.
• Click a node to open puzzle metadata in the right panel (always basic mode), matching table mode fields.
• Interactive puzzles show a read-only summary in the sidebar; use the link to open the full-screen puzzle editor (advanced) for URL / pack changes.
• Full-screen puzzle editing opens in a new tab—useful for large Hunts and unlock chains.
• Visual mode focuses on structure; saves still write to draft structure_json.

• Normal / Meta / Final Meta / Bonus / Hidden / Story: Meta and FM affect default points and hint-coin prices (about 10 / 100 / 1000). Story puzzles cannot use the interactive carrier (lint error).
• Body carrier (advanced): Switch HTML rich text | Interactive in the full-screen editor; basic mode is HTML only.
• Interactive: Pick a pack from the Hunt / creator asset library (not a generic image host). ZIP packs usually need review.
• Flavor text: Editable under HTML.
• Answers, Answer Gate, intermediate match modes (including regex on the player's raw text), unlock HTML, content warnings. Regex syntax is in the full-screen editor: Advanced mode guide → Answers JSON & matching.
• Branches, Penpa, wiki links, and the rich toolbar match the standalone editor.
• Check interactive puzzles at immersive, side-by-side, and phone widths (viewport, fluid width, touch). Do not hard-code a fixed-pixel canvas.

How to get the SDK

The platform ships the interactive puzzle SDK built in—no separate download or signup. Add this to your package root index.html:

<script src="/hunt-sandbox-sdk.js"></script>

When players open an interactive puzzle, the platform runs your page in an isolated environment and serves the script from the same site.

How to use it

After the script loads, window.PuzzleHuntSandbox exposes:

| Method | Purpose | |--------|--------| | ready() | Tell the parent the puzzle is ready (called once automatically on load) | | reportHeight() | Report content height so the parent can resize the iframe | | submitProgress(data) | Send progress / custom events (object is JSON-serialized) | | log(message) | Send a debug log line to the parent | | getContext() | Read the context injected by the parent: { ctx: {huntId, puzzleId}, hunt: {structure, progress, solvedAnswers}, snapshot }. hunt.structure / progress mirrors the sections, puzzles, and unlock state visible to this team; solvedAnswers contains answers of solved puzzles only; snapshot is the cross-puzzle state snapshot. Use onContext(fn) to subscribe to the injection moment | | useTeamState(key) / usePlayerState(key) | Cross-puzzle state: returns { get(), set(value), subscribe(fn), reload() }. team is shared by the whole team, player is per member; both are bound to the team and released when it disbands. After puzzle A calls set, puzzle B (or a refreshed page) can get it |

Example (report progress on button click):

<button onclick="PuzzleHuntSandbox.submitProgress({ step: 2 })">Next</button>

Cross-puzzle state channel

State is persisted by the parent page via postMessage (stored per Hunt + team); your package needs no credentials and never calls the backend directly. On iframe ready the parent injects the context and a state snapshot in one shot; later reads/writes happen on demand. There is no real-time push across members — teammates see the latest value when they open the puzzle.

⚠️ Read before write: state is stored per key as whole-value replacement (no merging). Before set(), always fetch the latest value via reload() / get() / subscribe(), merge locally, then write back; writing without reading first will discard data saved by teammates or other pages.

<script>
  var notes = PuzzleHuntSandbox.useTeamState('notes');
  notes.subscribe(function (v) { /* render v */ });
  notes.set({ strokes: '...' });
</script>

Limits: keys are 1-128 chars from [A-Za-z0-9_.:-]; each value ≤128KB; ≤1MB per scope; ≤20 entries per batch. Compress large content such as drawing notes first (e.g. lower the resolution when exporting a dataURL).

Notes

• The SDK does not replace the official answer box; players still submit answers in the field below the puzzle.
• Do not embed correct answers or unpurchased hint text in the package.
• ZIP packages must include index.html at the root; test in editor Preview or the asset library before publishing.
• For upload steps, see Interactive puzzles in the Puzzle creator guide.

Reading-width adaptation (author's job)

Players can use immersive, side-by-side, or phone layouts; the iframe width changes a lot. The platform will not inject a viewport or scale your canvas. Use fluid layout and playtest all three widths.

The puzzle edit page (Hunt full-screen puzzles and standalone puzzles share the same editor shell):

• Layout: Title, flavor, and body on top; puzzle settings (answers, unlock, hints, credits, etc.) scroll below the body module.
• Basic / advanced mode: Basic uses forms and the rule builder; advanced adds HTML source, answer JSON, unlock AST, and body carrier tabs in the main area.
• Switching carriers: In advanced mode, switching HTML ↔ interactive keeps unsaved content until you save the draft.
• Rich text: The format bar supports size, color, lists, and images (data-asset-id from the asset library).
• Save: Use Save draft manually; no edits while under platform review.
• Playtest / preview: Hunt puzzles open testsolver; during review you can playtest the submitted draft read-only without writing changes.
• Puzzle titles have a length limit and disallow list markers and similar rich-text symbols.

For team-created Hunts, each puzzle can list puzzle authors (comma-separated) and a display policy:

• Show directly: Authors are visible on the puzzle page and map cards.
• Show after solve: Shown after the team solves the puzzle or finishes the Hunt.
• Hidden: Recorded in the backend only; not shown to players.

This complements Hunt-level public lead credits: leads are event organizers; puzzle authors are puzzle contributors.

Each puzzle’s unlock rule determines when it moves from locked to unlocked:

• Basic mode: Rule builder choices such as always, solve a puzzle, section completion count, N hours after start, etc.
• Advanced mode: JSON AST supporting and / or / not / allSolved / anySolved / kOfSolved / sectionSolvedCount / timeAfterStart, and more.
• Structure lint runs before save: detects circular dependencies, orphan puzzles, missing FM, invalid puzzleId, etc.
• Staff can manually unlock teams from the dashboard.

Two hint mechanisms work side by side:

Fixed hints + hint coins

• Enable hint economy under Registration & finish: currency name, starting balance, timed coin grants, coins on correct answers, custom earningRules.
• Configure multiple fixed hints per puzzle: title, body, price, order; the server returns content only after purchase.
• Player APIs: GET .../hints/balance, GET .../puzzles/:id/hints (metadata only, no hint body).

Manual hints (Staff)

• Players request a manual hint on the puzzle page → enters the Hunt hint queue; Staff replies are pushed via the Hunt notification bell.
• Billed separately from fixed hint purchases; suited to narrative hints or those hard to price.

• Pre-registration / in-event registration / join team during event: Control when teams can be created or joined.
• Team size: min / max; allow solo teams; team names are subject to length limits and blocklists.
• Division: Register with a division code when multiple tracks exist; leaderboards can filter by division.
• Finish rules: solve_any_fm, solve_all_fm, specified puzzle sets, K puzzles in a section, K puzzles globally, etc.
• After a team finishes, notifications fire; players can submit overall ratings and per-puzzle feedback.

• Scoring rules: Points per puzzle, Meta/FM defaults, wrong-answer penalties, optional speed bonuses.
• Leaderboard: enabled master switch; visibleDuringEvent whether visible during the event; hideUntilEnd interacts with the former.
• allowTeamOptOut: teams may opt out of the public board; sortBy is finish (finish time) or score (points).
• maskUntilFinish: unfinished teams may appear masked on the board.
• frozen / freezeAt: freeze the board for post-event snapshots.
• Teams that include testsolvers are excluded from the public board by default.

Under Answer grading, configure answer matching rules (case, spaces, punctuation, Han variants, full/half width) and wrong-answer policy:

• none: No cooldown (still subject to max attempts if enabled).
• cooldown_escalation: Cooldown increases after wrong answers up to maxCooldownSeconds; optional linear, exponential, or custom formula.
• max_attempts: Maximum submissions per puzzle.

The player UI shows a cooldown countdown; 429 responses include cooldownSeconds.

• Structure lint: One-click lint on the edit page; run before publish.
• Testsolvers: Generate invite links; if unresolved feedback is high, consider delaying publish.
• Ops dashboard (/creator/hunts/:id/dashboard): Teams, finishes, hint queue, pending assets, security events, puzzle pass rates.
• Announcements / errata (/creator/hunts/:id/ops): Push to registered teams via Hunt notifications; can be pinned.
• Passing structure lint ≠ ready to publish—also consider test coverage and feedback handling.

• Upload images, HTML, ZIP interactive packages, etc.; file size and formats are limited (interactive packages usually require review).
• New assets may be pending and must be approved before puzzle bodies can reliably reference them.
• Reference format in puzzle bodies: asset:assetId; the rich-text editor can insert approved assets.
• Interactive puzzles run in an isolated environment.

• On the Hunt achievements page, define display name, achievement slug, icon colors, and auto-award conditions (rank, finish, first blood, time window, etc.).
• Achievements are awarded automatically by rules or manually by Staff, and shown only after the Hunt ends; they are not platform-wide badges.
• Quick templates cover common cases such as champion, top ten, no-hint clear, first blood, and finish.

• Solution notes: Write per-puzzle HTML in the collapsed Solution explanation section; published with the Hunt version; players browse the wrap-up after they finish.
• Visibility: Wrap-up and discussion become visible after the team finishes (staff / testsolver preview excepted).
• You can control whether wrap-up is public and when it opens; if no time is set, long-term Hunts allow access after finish, regular Hunts require the event to end.
• When the public switch is off, players do not see an entry (including after they finish).

• publicDiscussionEnabled / discussionRevealAt: Control discussion independently; finish is still required.
• Wrap-up and discussion can open at different times.
• Manage spoilers; admins can hide posts.
• Community discussion is separate from official solution notes and the wrap-up page.

• After finishing, teams can submit an overall Hunt rating (1–5 stars).
• Optionally complete a per-puzzle survey with two dimensions: difficulty and fun.
• Only solved puzzles can be rated; data helps creators improve and does not affect the leaderboard.
• Home Popular Puzzlehunts can rank by overall rating and participation.

1. Save the draft and confirm puzzlePanelMode (list / visual) and puzzleEditorMode (basic / advanced) match your intent.
2. Run lint and fix errors; address warnings.
3. Invite testsolvers and cover main unlock chains and FM.
4. Submit for review under Publish & tools (pending_review / pending_update_review).
5. After admin approve, the published version points to the new version; the player site reads published_version.

You cannot edit the draft directly while under review; if rejected or changes are requested, revise per review notes and resubmit.

Pre-publish checklist (for creators)

Before submitting for review or opening registration, confirm:

• [ ] Complete puzzle bodies: Every puzzle has a title and body (or interactive pack)—no empty placeholders.
• [ ] Correct answers: Final answers and aliases are set; you can self-solve the main path.
• [ ] Unlock flow: Structure lint shows no errors; testsolvers walked the main unlock chain.
• [ ] Hints ready: Fixed hint text is written; if hint coins are enabled, prices and starting balance look right.
• [ ] Assets approved: Referenced images / interactive packs are approved.
• [ ] Schedule & rules: Start/end times, timezone, FAQ, contact info, and finish rules are filled in.
• [ ] Visual polish: Theme and banner look readable in preview.
• [ ] Fair play: No answers inside interactive packs; no spoilers for locked content in puzzle text or discussion.

After the event starts

• Use announcements / errata for in-event fixes.
• After finish, publish wrap-up solutions and review ratings and discussion (manage spoilers).

---

*This document is exported from the Puzzle Cat creator guide page and kept in sync with editor features.*