puzzle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Puzzle

解谜游戏开发指南

A playbook for grid/board puzzle games — the board model, move input, rule resolution (matching, pushing, logic), scoring, undo, and level progression. This is a compositional skill: it models board state and rules and presents them through a tilemap/UI. It does not re-teach tilemaps; it defines the resolution loop and the correctness rules (clean state, deterministic resolution, undo) that keep a puzzle fair and bug-free.

这是一份网格/棋盘类解谜游戏的开发手册——涵盖棋盘模型、移动输入、规则结算（匹配、推动、逻辑）、计分、撤销以及关卡进度系统。这是一项组合式技能：它负责建模棋盘状态与规则，并通过瓦片地图/UI呈现。本内容不会重新讲解瓦片地图；它定义了结算循环与正确性规则（干净状态、确定性结算、撤销），以确保解谜游戏的公平性与无bug运行。

When to use

适用场景

Use when the game is a discrete board the player changes with moves, and the board resolves by rules: match-3/tile-matching, sokoban/block-pusher, sliding puzzle, logic grid.
Use when designing match/cascade resolution, undo, level progression, or solvability.

When not to use: real-time grid action with permadeath →

roguelike

. Card zones/turns →

card-game

. Physics-based "puzzle platformer" →

platformer

physics-tuning

. For the tile rendering, use

godot-tilemap

unity-tilemap-2d

当你的游戏是玩家通过移动操作改变离散棋盘，且棋盘会根据规则自动结算时适用：match-3/方块匹配类、sokoban/推箱子类、滑动拼图、逻辑网格类游戏。
当你需要设计匹配/连锁结算、撤销、关卡进度或可解性机制时适用。

不适用场景：带有永久死亡机制的实时网格动作游戏 → 参考

roguelike

。带有卡牌区域/回合制的游戏 → 参考

card-game

。基于物理的“解谜平台游戏” → 参考

platformer

physics-tuning

。瓦片渲染请使用

godot-tilemap

unity-tilemap-2d

。

Core loop

核心循环

Read the board → plan a move → make the move → the board resolves by its rules (match, push, fall, fill, cascade) → see progress toward the objective → repeat until solved/failed. The fun is the planning; the engine's job is to resolve each move deterministically and present it clearly.

读取棋盘 → 规划移动 → 执行移动 → 棋盘根据规则结算（匹配、推动、下落、填充、连锁） → 查看目标进度 → 重复直至通关/失败。 游戏的乐趣在于规划；引擎的职责是确定性地结算每一步操作，并清晰呈现结果。

Must-have systems

必备系统

Board model — a grid of cells holding pieces; the single source of truth (logic, not visuals).
Move input — swap, push, drag, rotate, or place; validate legality before applying.
Rule resolution — detect and apply the genre's rule (matches, pushes, logic) until stable.
Cascades/chains — when resolution changes the board, re-resolve until no more changes.
Objectives + scoring — win/lose conditions (score, clear all, reach goal); move/time limits.
Undo — revert the last move (and its resolution) exactly; essential for thinky puzzles.
Level progression + (often) generation — hand-authored or generated solvable boards.
Feedback ("juice") — clear, satisfying animation/sound for matches, falls, and chains.

棋盘模型 —— 由存储方块的单元格组成的网格；是唯一的事实来源（逻辑层面，非视觉层面）。
移动输入 —— 交换、推动、拖拽、旋转或放置；在应用前验证操作合法性。
规则结算 —— 检测并应用对应品类的规则（匹配、推动、逻辑）直至状态稳定。
连锁/链式反应 —— 当结算改变棋盘状态时，重新执行结算直至无更多变化。
目标与计分 —— 胜负条件（得分、清空棋盘、到达目标）；移动次数/时间限制。
撤销功能 —— 精确还原上一步操作（及其结算结果）；对策略类解谜游戏至关重要。
关卡进度 + （通常包含）生成 —— 手工制作或生成的可解棋盘。
反馈（“润色”） —— 匹配、下落、连锁时清晰且令人愉悦的动画/音效。

Design knobs

设计调整项

Knob	Effect	Notes
Grid size / shape	complexity	Square is standard; hex/irregular change feel.
Match/push rule	genre identity	3-in-a-row, shapes, push-into-goal, etc.
Cascade scoring	reward depth	Bigger chains = exponential payoff.
Move / time limit	pressure	Move-limited = puzzly; time = arcade.
Difficulty curve	learning	Introduce one mechanic at a time.
Undo depth	forgiveness	Single-step vs. full history.
Solvability guarantee	fairness	Generated boards must be solvable.
Deadlock handling	no dead ends	Detect no-moves; shuffle or end (refs).

调整项	效果	说明
网格大小/形状	复杂度	方形为标准；六边形/不规则形状会改变游戏手感。
匹配/推动规则	品类特性	三连消、形状匹配、推至目标等。
连锁计分	深度奖励	更长的连锁反应 = 指数级得分回报。
移动次数/时间限制	压力感	限制移动次数 = 策略解谜向；限制时间 = 街机向。
难度曲线	学习体验	每次仅引入一种机制。
撤销深度	容错性	单步撤销 vs 完整历史撤销。
可解性保障	公平性	生成的棋盘必须可解。
僵局处理	避免死局	检测无有效操作的情况；洗牌或结束关卡（参考相关文档）。

Patterns

模式示例

1. Board model + match detection (logic separate from visuals)

1. 棋盘模型 + 匹配检测（逻辑与视觉分离）

python

undefined

python

undefined

Pseudocode. The board is the truth; rendering reads from it. (0,0) top-left, y grows down.

伪代码。棋盘是唯一事实来源；渲染从棋盘读取数据。(0,0)为左上角，y轴向下增长。

board = [[piece_or_empty for _ in range(W)] for _ in range(H)]

def find_matches(board): matched = set() for y in range(H): # horizontal runs of >= 3 equal pieces run = 1 for x in range(1, W): if board[y][x] and board[y][x] == board[y][x-1]: run += 1 else: if run >= 3: matched |= {(y, k) for k in range(x-run, x)} run = 1 if run >= 3: matched |= {(y, k) for k in range(W-run, W)} # ... repeat the same scan vertically (columns) ... return matched

undefined

board = [[piece_or_empty for _ in range(W)] for _ in range(H)]

def find_matches(board): matched = set() for y in range(H): # 水平方向连续≥3个相同方块的序列 run = 1 for x in range(1, W): if board[y][x] and board[y][x] == board[y][x-1]: run += 1 else: if run >= 3: matched |= {(y, k) for k in range(x-run, x)} run = 1 if run >= 3: matched |= {(y, k) for k in range(W-run, W)} # ... 重复相同扫描逻辑处理垂直方向（列） ... return matched

undefined

2. Resolve → collapse → refill → cascade (repeat to stability)

2. 结算 → 塌陷 → 填充 → 连锁（重复直至稳定）

python

undefined

python

undefined

Pseudocode. One player move can trigger a chain; loop until the board stops changing.

伪代码。一次玩家操作可能触发连锁反应；循环执行直至棋盘状态停止变化。

def resolve(board): chain = 0 while True: matches = find_matches(board) if not matches: break # stable: resolution complete chain += 1 score += score_for(matches, chain) # later chain steps score more (see refs) clear(board, matches) # remove matched pieces apply_gravity(board) # pieces fall into the gaps refill(board, rng) # spawn new pieces at the top (seeded RNG) return chain

undefined

def resolve(board): chain = 0 while True: matches = find_matches(board) if not matches: break # 状态稳定：结算完成 chain += 1 score += score_for(matches, chain) # 后续连锁步骤得分更高（参考相关文档） clear(board, matches) # 移除匹配的方块 apply_gravity(board) # 方块下落填补空隙 refill(board, rng) # 在顶部生成新方块（使用带种子的随机数生成器） return chain

undefined

3. Undo via state snapshot or command

3. 通过状态快照或命令模式实现撤销

python

undefined

python

undefined

Pseudocode. Snapshot before each move; undo restores it exactly (board + score + counters).

伪代码。每次操作前创建快照；撤销操作会精确恢复快照状态（棋盘 + 得分 + 计数器）。

def make_move(move): history.append(snapshot(board, score, moves_left)) # push BEFORE applying apply(move); resolve(board); moves_left -= 1

def undo(): if history: board, score, moves_left = history.pop() # exact revert, including resolution


For large boards prefer the **command** pattern (store the move + enough to invert it) over full
snapshots to save memory; snapshots are simplest and fine for small boards.

def make_move(move): history.append(snapshot(board, score, moves_left)) # 应用操作前先保存快照 apply(move); resolve(board); moves_left -= 1

def undo(): if history: board, score, moves_left = history.pop() # 精确还原，包括结算结果


对于大型棋盘，建议优先使用**命令模式**（存储操作及其反转所需的信息）而非完整快照，以节省内存；快照实现最简单，适用于小型棋盘。

Pitfalls / failure modes

常见陷阱/失败模式

Mixing logic and visuals → animations desync from state and cause bugs. The board model is the single source of truth; the view only renders it.
Resolving only once → cascades/chains are missed. Loop resolution until the board is stable (Pattern 2).
Undo that doesn't restore everything → score/move-count/random-state drift. Snapshot all state, or make the move fully invertible.
Unseeded refill RNG → can't reproduce a level / no deterministic undo or daily puzzle. Seed it.
Generated boards that aren't solvable → unfair dead ends. Generate-and-verify, or generate from a known solution backward (refs).
No deadlock detection (match-3) → board with no valid moves softlocks. Detect "no moves" and shuffle or end the level (refs).
Difficulty spikes → too many mechanics at once. Teach one mechanic per level before combining.
Resolution mid-animation accepts input → double-moves/corruption. Lock input until the board is stable.

逻辑与视觉混合 → 动画与状态不同步，导致bug。棋盘模型是唯一的事实来源；视图仅负责渲染。
仅执行一次结算 → 遗漏连锁/链式反应。循环执行结算直至棋盘状态稳定（参考模式2）。
未完全恢复所有状态的撤销功能 → 得分/移动次数/随机状态偏差。快照所有状态，或确保操作完全可逆。
未设置种子的填充随机数生成器 → 无法复现关卡 / 无法实现确定性撤销或每日谜题。请为随机数生成器设置种子。
生成不可解的棋盘 → 不公平的死局。采用“生成-验证”模式，或从已知解反向生成棋盘（参考相关文档）。
无僵局检测（match-3类游戏） → 棋盘无有效操作时陷入软锁。检测“无有效操作”状态并执行洗牌或结束关卡（参考相关文档）。
难度陡增 → 一次性引入过多机制。在组合机制前，每关只教授一种机制。
结算动画期间接受输入 → 重复操作/状态损坏。在棋盘状态稳定前锁定输入。

Composition (build it from these skills)

组合构建（基于以下技能）

Board rendering:
```
godot-tilemap
```
/
```
unity-tilemap-2d
```
for the grid;
```
godot-ui-control
```
for HUD, score, and menus.
Levels:
```
level-design
```
for hand-authored puzzles and difficulty pacing;
```
procedural-gen
```
for solvable generated boards.
Persistence:
```
save-systems
```
for level progress, high scores, and seeded daily puzzles.
Juice:
```
game-feel
```
for match/cascade pop, screen shake, and chain feedback; the engine animation/
```
Tween
```
skill for swaps/falls/clears;
```
audio-design
```
for match and chain cues.
Scripting:
```
godot-gdscript
```
/
```
unity-csharp-scripting
```
for the resolution loop and rules.

棋盘渲染：使用
```
godot-tilemap
```
/
```
unity-tilemap-2d
```
实现网格；使用
```
godot-ui-control
```
实现HUD、计分与菜单。
关卡：使用
```
level-design
```
制作手工谜题并规划难度节奏；使用
```
procedural-gen
```
生成可解的棋盘。
持久化：使用
```
save-systems
```
保存关卡进度、高分记录与带种子的每日谜题。
润色：使用
```
game-feel
```
实现匹配/连锁的视觉冲击、屏幕震动与连锁反馈；使用引擎动画/
```
Tween
```
技能实现交换/下落/清除动画；使用
```
audio-design
```
实现匹配与连锁音效。
脚本编写：使用
```
godot-gdscript
```
/
```
unity-csharp-scripting
```
实现结算循环与规则逻辑。

References

参考资料

For match-3 detection/gravity/refill/cascade detail, deadlock detection and reshuffles, sokoban/rule-based puzzles, undo strategies, solvable generation, and scoring, read
```
references/board-and-resolution.md
```
.

如需了解match-3的检测/重力/填充/连锁细节、僵局检测与重排、sokoban/基于规则的谜题、撤销策略、可解性生成与计分机制，请阅读
```
references/board-and-resolution.md
```
。