PuzzleCat

Puzzlehunt 创作指南

本指南详细介绍 Puzzlehunt 编辑器的全部功能分区与配置要点。如需按需查阅,可点击右上方「下载 Markdown」导出全文,并将其提供给大语言模型,以便就具体功能查询相应的设置方法。

创作规范

投稿前请先阅读本节。以下规范适用于 Hunt 全部内容与运营行为,与平台审核、下架及账号处理相关。

一稿多投与跨平台发布

  • 本站支持一稿多投:您可以将同一个谜题活动同时发布到本平台和其他平台。
  • 在进行一稿多投前,请务必先确认其他平台是否允许跨站发布,以免产生版权纠纷或其他不必要的问题。
  • 若其他平台对「首发」「独家」或转载范围有约定,请自行遵守;本站不对您与其他平台之间的协议承担保证责任。

重制版 Hunt

  • 本站鼓励上传重制版 Hunt(以往举办过的活动在本站重新上线),并在「基本信息」中勾选标记为重制 Hunt
  • 上传时可填写原始链接原始发布时间,玩家端会显示「重制」标签并展示出处,便于新老玩家识别。
  • 请勿将重制版 Hunt 误标为全新首发;若对题目、规则或赛程做了较大改动,建议在摘要或 FAQ 中说明差异。

版权与授权

  • 您应确保对上传的题面、图片、音频、交互包、地图素材等享有合法使用权或已获授权;不得侵犯他人著作权、商标权、肖像权或其他合法权益。
  • 团队共创时,请事先与成员约定署名与权利归属,并在 Hunt 内正确填写主创与出题人信息。
  • 引用第三方素材(字体、音乐、影视截图、品牌元素等)时,请确认许可范围是否允许公开赛事使用与长期在线展示。

法律与合规

您提交的内容与运营行为须遵守所有适用的法律法规。您有责任确保相关活动在任何运营所涉国家或地区均完全合规。若 Hunt 面向特定国家或地区的玩家,您还需自行评估当地对在线赛事、抽奖、未成年人参与、数据收集等方面的额外要求。

内容安全与玩家体验

  • 不得发布违法、暴力煽动、仇恨歧视、骚扰、诈骗、恶意代码或明显不适合公开赛事的内容。
  • 不得发布恐怖、血腥、成人向等题材。
  • 不得利用题面、资源或交互包绕过平台答案与提示保护机制,或在未解锁/未购提示前泄露关键信息。
  • 发布前请完成自测与测试员覆盖;赛中请通过公告、勘误及时修复影响公平或可玩性的问题。

数据与隐私

  • 若 Hunt 收集报名邮箱、联系方式或其他个人信息,请仅用于赛事沟通与运营所必需的范围,并遵守适用的隐私与数据保护规则。
  • 请勿在题面、规则或公告中公开要求玩家提交密码、完整证件号、银行卡信息等敏感数据。

平台审核

  • 违反上述规范的内容可能被要求修改、暂缓发布或下架;严重或重复违规可能导致创作权限受限。
  • 如对审核结论有疑问,可通过 Hunt 内联系方式或站内反馈渠道与平台沟通。

基本信息与赛程

在 Hunt 编辑器的「基本信息」分区填写 Hunt 对外展示与赛程相关字段:

  • 标题:列表与详情页主标题。
  • 自定义访问路径(Slug):用于自定义链接(如 https://puzzle.cat/hunt/summer-2026;默认 ID 链接仍为 /hunts/{id})。仅支持小写英文、数字与连字符,至少 4 个字符;留空则由系统根据标题自动生成。
  • 摘要:Hunt 列表与详情简介。
  • 标签:多个标签用英文逗号分隔,便于玩家检索。
  • 联系方式 / FAQ / 规则说明:显示在 Hunt 详情页供参赛者查阅。
  • 开赛 / 结束时间:配合时区决定「即将开始」「进行中」「已结束」;定时解锁规则依赖赛程。
  • Hunt 类型常规赛事需设置结束时间;长期 Hunt 无结束时间,开赛后持续开放,且赛中报名默认不可关闭。
  • 可见性public 公开列表可见;unlisted 仅链接可访问;private 需权限。
  • 重制 Hunt:勾选后可填原始链接与原始发布时间(见「创作规范」)。
  • 时区:影响榜单时间展示与 timeAfterStart 类解锁规则。
  • 归属创作团队:可选绑定长期团队;成员不会自动获得编辑权限,需在「共创」中单独授权。
  • 投稿到平台活动:可将本 Hunt 关联至进行中的平台活动,用于活动页展示与积分(若活动开启投稿)。

团队共创

多人协作时可绑定创作团队并在 Hunt 内配置共创权限

  • 创作团队:长期组织,成员可复用到多个 Hunt;新建 Hunt 时可预选团队并批量添加初始作者。
  • 我的 Hunt →「共创」:为单场 Hunt 添加主策划 / 协作者 / 分区负责人 / staff / testsolver 等角色。
  • staff 可访问运营仪表板、公告勘误、人工提示队列;testsolver 仅能测试游玩,不可改草稿。
  • 公开主创名单在 Hunt 详情展示;每题还可单独填写出题人(见「出题人署名」)。

视觉主题

「视觉与头图」分区控制玩家端题图与谜题页的整体风格:

  • 从预设(如 neon-dark)一键应用主色、强调色、背景与圆角。
  • 背景模式:纯色、渐变或图片;头图 / Banner 用于列表卡片与详情顶栏。
  • 卡片透明度 / 边框光晕:调节题图卡片在背景上的可读性。
  • 背景图请通过资源库上传后引用,避免外链不可控域名。

区域与题目

题图由区域(Section)题目(Puzzle)组成:

  • 区域可嵌套 parentId,用于分区 Meta、章节式布局;每区可设宽度(列数)与地图坐标。
  • 「题目列表」表格支持折叠行内编辑:标题、区域、类型、分值、解锁摘要、提示数量。
  • 「地图编辑器」可拖拽题目在区域内的 layoutX / layoutY,自定义背景图作为区域底图。
  • 题目 ID 在结构内唯一,解锁规则、解报、评分均引用该 ID,请勿随意改名已发布题目。

可视化编辑

在「题目」分区切换到可视化模式(或编辑页 URL ?mode=visual):

  • React Flow 画布展示题目节点与解锁连线;拖拽节点调整布局。
  • 点击节点在右侧面板打开题目元数据编辑(固定基础模式),与表格模式字段一致。
  • 交互题在侧栏为只读摘要,请通过链接进入全屏题目编辑器(高级模式)修改 URL / 选包。
  • 支持全屏题目编辑(新标签),适合大型 Hunt 梳理解锁链。
  • 可视化侧重结构,保存仍写入草稿版 structure_json

题型与答案

  • 普通 / Meta / Final Meta / Bonus / 隐藏 / 剧情:Meta、FM 影响默认分值与提示币价格(约 10 / 100 / 1000)。剧情题不可使用交互题载体(lint 报错)。
  • 题面载体(高级模式):全屏编辑器主区切换 HTML 富文本 | 交互题(iframe);基础模式仅 HTML 纸面。
  • 交互题:填写 URL 或 asset:资源ID;从 Hunt / 创作者资源库选择交互题包(zip 通常需审核)。
  • Flavor Text:HTML 载体下可编辑风味段。
  • 正确答案与别名Answer Gate中间答案内容警告:同前;高级模式可编辑答案 JSON 与解锁 AST。
  • 交互题静态包勿内置答案或未购提示正文;如需与平台页面通信,请阅读下一节「交互题 SDK」。

交互题 SDK

如何获取 SDK

平台已内置交互题 SDK,无需单独下载或申请。在交互包根目录的 index.html 中加入:

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

玩家端加载交互题时,平台会在 iframe 沙盒中运行你的页面,并自动注入上述脚本路径(与站点同源)。本地调试时也可在浏览器直接打开 https://你的域名/hunt-sandbox-sdk.js 查看源码注释。

如何使用

引入脚本后,全局对象 window.PuzzleHuntSandbox 提供以下方法:

| 方法 | 说明 | |------|------| | ready() | 通知父页面交互题已就绪(脚本加载后会自动调用一次) | | reportHeight() | 手动上报内容高度,父页面会调整 iframe 高度 | | submitProgress(data) | 向父页面发送进度/自定义事件(对象会 JSON 序列化传递) | | log(message) | 向父页面输出调试日志 |

示例(按钮点击时上报进度):

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

注意事项

  • SDK 不能代替正式答案提交;玩家仍需在题页下方的答案框输入并提交。
  • 勿在交互包内写入正确答案或未购买提示的正文。
  • ZIP 包根目录须包含 index.html;上传前请在编辑器「预览」或资源库试玩中自测。
  • 更多上传步骤见 谜题创作指南 的「交互题」一节。

题目编辑器

谜题编辑页(Hunt 全屏题目与独立谜题共用同一套编辑器壳):

  • 布局:题目标题、风味段、正文在上方;题目设置(答案、解锁、提示、署名等)在正文模块下方滚动区。
  • 基础 / 高级模式:基础模式用表单与规则构建器;高级模式可编辑 HTML 源码、答案 JSON、解锁 AST,并在主区切换正文载体
  • 正文载体双缓冲:高级模式下 HTML ↔ 交互题切换时,未保存前各自草稿保留在浏览器 session 中。
  • 富文本:顶栏格式条支持字号、颜色、列表、图片(须从资源库插入 data-asset-id)。
  • 保存:请使用「保存草稿」手动保存;审核中无法修改。
  • 试玩 / 预览:Hunt 题目可打开 testsolver;审核中可只读试玩已提交草稿,不写入新修改。
  • 题目标题有字数上限,且禁止列表标记等富文本符号。

出题人署名

团队创作时,每题可填写出题人(多人用英文逗号分隔),并选择展示策略:

  • 直接展示:玩家在题面/地图卡片上可见出题人。
  • 通关后展示:队伍解出该题或完赛后才显示。
  • 不展示:仅后台记录,玩家端不显示。

与 Hunt 级「公开主创名单」互补:主创是赛事组织角色,出题人是谜题贡献者。

解锁流程

每题 unlockRule 决定何时从 locked 变为 unlocked:

  • 基础模式:规则构建器选择 always、解出某题、区域完成数、开赛 N 小时等。
  • 高级模式:JSON AST,支持 and / or / not / allSolved / anySolved / kOfSolved / sectionSolvedCount / timeAfterStart 等。
  • 保存前运行结构校验(lint):检测环依赖、孤儿题、FM 缺失、无效 puzzleId 等。
  • Staff 可在仪表板对队伍做手动解锁(写入 progress manualUnlocks)。

提示

两类提示机制并存:

固定提示 + 提示币

  • 在「报名与通关」启用提示经济:货币名称、初始余额、定时发币、答对发币、自定义 earningRules。
  • 每题配置多条固定提示:标题、正文、价格、排序;玩家购买后服务端才返回 content。
  • 玩家 API:GET .../hints/balanceGET .../puzzles/:id/hints(仅元数据,无正文)。

人工提示(Staff)

  • 玩家在题页「申请人工提示」→ 进入 Hunt 的提示队列;Staff 回复后通过 Hunt 通知铃铛推送。
  • 与固定提示购买分开计费,适合剧情向或不便标价的提示。

报名与通关

  • 预报名 / 赛中报名 / 赛中加入队伍:控制何时可创建或加入队伍。
  • 队伍人数:min / max;是否允许单人队;队伍名称受字数与屏蔽词约束。
  • 赛道 Division:多赛道时用赛道代号报名;排行榜可按 division 筛选。
  • 通关规则solve_any_fmsolve_all_fm、指定题集、区域 K 题、全局 K 题等。
  • 完赛时队伍 finished_at 写入,触发通知;玩家可提交总评分与每题反馈。

计分与排行榜

  • 计分规则:按题分值、Meta/FM 默认分、错答扣分、速度加分(可选)。
  • 排行榜enabled 总开关;visibleDuringEvent 赛中是否可见;hideUntilEnd 与前者联动。
  • allowTeamOptOut:队伍可自愿不上榜;sortBy 为 finish(完赛时间)或 score(积分)。
  • maskUntilFinish:未完赛队伍在榜上可脱敏显示。
  • frozen / freezeAt:冻结榜单用于赛后定格。
  • 含测试员的队伍默认不上公开榜。

答案与判题

在「答案与判题」分区可配置答案比对规则(大小写、空格、标点、简繁、全半角)与答错策略:

  • none:无冷却(仍受最大尝试次数约束若启用)。
  • cooldown_escalation:错答后冷却递增,直至 maxCooldownSeconds;可选线性、指数或自定义公式。
  • max_attempts:每题最大提交次数。

玩家端显示冷却倒计时;429 响应含 cooldownSeconds

运营与测试

  • 结构校验:编辑页一键 lint,发布前必跑。
  • 测试员:生成邀请链接;测试员反馈 unresolved 过多时建议暂缓发布。
  • 运营仪表板/creator/hunts/:id/dashboard):队伍数、完赛数、提示队列、资源待审、安全事件、题目通过率。
  • 公告 / 勘误/creator/hunts/:id/ops):推送至参赛队伍 Hunt 通知;可置顶。
  • 结构 lint 通过 ≠ 可发布,请结合测试覆盖率与反馈处理状态。

资源库

  • 上传图片、HTML、ZIP 交互包等;文件存储在 OSS,单文件大小与 MIME 类型受服务端限制(交互包通常需审核)。
  • 新资源可能为 pending,需管理员审核为 approved 后题面方可稳定引用。
  • 题面引用格式:asset:资源ID;富文本编辑器可插入已审核资源。
  • 访问经 /api/hunts/:id/assets/:assetId/file 代理(HTTPS 签名源在 OSS),交互题运行在 iframe 沙盒内。

成就

  • 在 Hunt 成就页定义显示名称、成就代号、图标配色与自动发放条件(名次、通关、首杀、时间窗口等)。
  • 成就按规则自动发放或 Staff 手动颁发,仅在该 Hunt 赛后展示;不是平台全局勋章。
  • 快捷模板含冠军、前十、无提示全通、首杀、通关等常见场景。

赛后与解报

  • 解题解析:在题目编辑器「解题解析」折叠区(富文本)按题编写,随 Hunt 版本发布;玩家经 /hunts/:id/wrapup 聚合浏览。
  • 完赛前提:队伍 finished_at 非空后,才可见解题报告与讨论区(staff / testsolver 预览除外)。
  • publicSolutionsEnabled / solutionsRevealAt:控制解题报告是否开放及公开时间;留空时间时,长期 Hunt 完赛即可,常规赛事须 Hunt 已结束。
  • 关闭公开开关时,玩家端无入口且 API 返回 404。

讨论区

  • publicDiscussionEnabled / discussionRevealAt:独立控制讨论区开放;同样须队伍已完赛。
  • 与解题报告解耦:可先开讨论、后开解报(或相反)。
  • 注意剧透管理;管理员可隐藏不当内容。
  • 讨论为社区交流,官方解析见各题解题解析与 wrapup 页。

评分反馈

  • 队伍完赛后可提交 Hunt 总评分(1–5 星)。
  • 可选填写每题问卷:难度、趣味性两个维度。
  • 仅已解题目可评;数据供创作者改进,不影响排行榜。
  • 首页「热门 Puzzlehunt」可综合总评分与参与度排序。

发布审核

  1. 保存草稿,确认 puzzlePanelMode(list / visual)与 puzzleEditorMode(basic / advanced)符合预期。
  2. 运行 lint,修复 errors;处理 warnings。
  3. 邀请测试员,覆盖主要解锁链与 FM。
  4. 在「发布与工具」提交审核(pending_review / pending_update_review)。
  5. 管理员 approve 后发布版指向新 version,玩家端读取 published_version。

审核中不可直接改草稿;被拒稿或要求修改后按 review 意见返修再提交。

安全与上线清单

发布前自查(给出题人)

在提交审核或对外开赛前,建议逐项确认:

  • [ ] 题面完整:每题标题、正文(或交互包)已填写,无空白占位。
  • [ ] 答案正确:正确答案与别名已配置,自测可通关主线路。
  • [ ] 解锁合理:运行结构校验(lint)无 error;主要解锁链经测试员走通。
  • [ ] 提示就绪:固定提示文案已写好;若启用提示币,价格与初始余额符合预期。
  • [ ] 资源可用:题面引用的图片 / 交互包已通过审核(状态为 approved)。
  • [ ] 赛程与规则:开赛/结束时间、时区、FAQ、联系方式、通关规则已填写。
  • [ ] 视觉与头图:玩家端主题、Banner 在预览中可读、美观。
  • [ ] 剧透与公平:交互包内不含答案;未解锁内容不在题面或讨论中泄露。

开赛后运营提醒

  • 赛中问题请通过公告 / 勘误及时告知玩家。
  • 完赛后可发布解题报告,并关注评分反馈与讨论区(注意剧透管理)。

---

*本文档由 Puzzle Cat 创作指南页导出,与编辑器功能同步维护。*

Puzzlehunt 创作指南 - PuzzleCat