---
summary: "Luật Full Rescue v2 mà mọi Tide Coach Agent phải hiểu"
title: "CORE-GAME-RULES.md — Shell Tide Full Rescue v2"
read_when:
  - Khởi tạo bất kỳ Tide Coach Agent nào
  - Tạo tutorial, hint, reaction hoặc recap gameplay
---

# Core Game Rules — Shell Tide Full Rescue v2

## Phạm vi và nguồn sự thật

File này định nghĩa core game dùng chung cho mọi Agent. Rule Analyzer và snapshot runtime hợp lệ của level hiện tại là nguồn sự thật cho legal move, preview, rescue event, số lượt và kết quả level.

Không dùng memory, lời thoại Agent hoặc ví dụ trong tài liệu để thay thế state runtime. Nếu tài liệu và snapshot mâu thuẫn, Agent mô tả trung tính và không tự suy đoán.

## Player promise và điều kiện thắng

Người chơi điều hướng hai FLOW quanh chu vi board, canh `STOP`, tạo Xoáy Cứu Hộ và đưa **toàn bộ sao biển** vào Vùng Nước An Toàn.

- Sao biển là token gameplay duy nhất trong 10 level Full Rescue v2.
- `remainingStarfish === 0` là điều kiện thắng bắt buộc.
- Cứu một phần, đạt combo hoặc dùng hết route không thể thay thế Full Rescue.
- Nắng nóng chỉ là bối cảnh kể chuyện; runtime v2 không có Heat meter, Heat state hoặc Heat fail.

## Cấu trúc board

- Board là graph vòng hai chiều map lên chu vi vuông.
- Template 3×3 dùng đủ 8 node chu vi và hồ trung tâm 1×1.
- Template 4×4 dùng đủ 12 node chu vi và hồ trung tâm 2×2.
- `centerLake` chỉ là layout/VFX: không có index, không giữ sao, không thể chọn và không thuộc `nodes`, `edges`, objective, lượt hoặc solver state.
- `sand` node có thể giữ sao và chỉ hợp lệ làm nguồn move khi đang có ít nhất một sao.
- `wet_pit` luôn rỗng, không thể chọn và cứu trực tiếp sao đi vào. Wet pit là modifier nâng cao do level data bật, không bắt buộc có hai node.

Agent dùng `nodeIndex` và topology do Rule Analyzer cung cấp, không suy diễn index từ vị trí hình học trên màn hình.

## Move hợp lệ và Dual Preview

Một move hợp lệ cần:

1. Chọn một `sand` node đang có ít nhất một sao.
2. Chọn một trong hai hướng topology `left` hoặc `right` mà level cho phép. Nếu node nguồn có Current Arrow, chỉ hướng của mũi tên là hợp lệ.
3. Preview và commit cùng `nodeIndex` + `direction`.

Preview có thể cung cấp:

- route node theo thứ tự;
- `STOP` của sao cuối cùng;
- Current Arrow và hướng rải bắt buộc tại node nguồn;
- Điểm Xoáy/capture candidate;
- Wet pit rescue dự kiến;
- số sao còn lại dự kiến nếu rule engine cho phép hiển thị.

Xem preview, đổi node, đổi hướng, mở Hint hoặc thao tác invalid không tăng `turnsUsed`.

## Sow, Current và Wet pit

Khi commit:

1. Lấy toàn bộ sao khỏi sand node nguồn.
2. Đi tuần tự qua topology theo hướng đã chọn và thả một sao vào mỗi sand node.
3. Nếu route đi vào Wet pit, sao đó rời board ngay và tăng rescue count; Wet pit vẫn rỗng.
4. Current Arrow chỉ khóa hướng khi chính node đó là nguồn của move; Dòng Chảy đi ngang qua không đổi hướng.
5. Node nhận sao cuối cùng là `STOP`.

Một move đã commit tăng `turnsUsed` đúng 1, bất kể route dài, số sao cứu hoặc số capture trong chain.

## Xoáy Cứu Hộ và capture chain

Sau `STOP`, runtime kiểm tra pattern theo hướng cuối cùng:

1. Node kế tiếp phải là sand node trống hợp lệ.
2. Sand node ngay sau đó phải có ít nhất một sao.
3. Toàn bộ cụm sao ở rich node bị capture và rời board.
4. Sau một capture, tiếp tục kiểm tra pattern kế tiếp để tạo capture chain.
5. Chain dừng ngay khi pattern tiếp theo không hợp lệ.

Chỉ empty node được Rule Analyzer trả trong `simulation.captures[].empty` mới là Điểm Xoáy. Không gọi mọi ô trống là xoáy.

## Final Tide Sweep

Khi `level.rules.finalTideSweep === true`, runtime chỉ được Sweep nếu:

- turn vừa tạo ít nhất một rescue hợp lệ; và
- board còn đúng một sand group có sao.

Sweep cuốn cụm cuối rời board, sau đó runtime vẫn kiểm tra `remainingStarfish === 0`. Agent không được yêu cầu Sweep, giả trigger hoặc mô tả nó như auto-solve tùy ý. Design progression hiện tại dành payoff này cho giai đoạn sau khi người chơi đã học Xoáy; snapshot level quyết định trạng thái thực tế.

## Tide Turns, lose và rating

- `turnsUsed`: số move hợp lệ đã commit.
- `optimalTurns`: số lượt Full Rescue nhỏ nhất do exact solver chứng minh.
- `maxTurns`: giới hạn lượt của attempt, được cân bằng từ optimal và recovery slack.
- Lose khi `turnsUsed >= maxTurns` và `remainingStarfish > 0`.
- Không có timer thời gian thực hoặc fail condition Heat thứ hai.

Rating chỉ được tính sau Full Rescue:

- 3★: `turnsUsed === optimalTurns`.
- 2★: `turnsUsed <= optimalTurns + ceil((maxTurns - optimalTurns) / 2)`.
- 1★: Full Rescue trong `maxTurns`.
- 0★: board chưa sạch hoặc đã vượt giới hạn.

Hint, Coach và booster không trực tiếp trừ sao; chúng chỉ có thể ảnh hưởng số lượt player thực tế dùng.

## Near-miss hợp lệ

Near-miss tốt thường có các dấu hiệu do Analyzer xác nhận:

- player đã cứu phần lớn sao;
- còn khoảng 10–30% sao, tập trung trong một rescue target rõ;
- nếu có thêm đúng một lượt, vẫn tồn tại một nước Full Rescue nhìn thấy được trong preview.

Agent chỉ recap target hoặc pattern cần quan sát, không đưa exact move sequence.

## Thứ tự resolve một lượt

```text
select legal sand node
→ choose topology direction
→ preview route + Current + STOP + rescue candidates
→ commit
→ sow starfish through sand nodes / rescue on Wet pit entry
→ resolve empty-then-rich capture chain
→ optionally resolve Final Tide Sweep
→ turnsUsed += 1
→ evaluate remainingStarfish
→ resolve Full Rescue rating, continue, or lose at maxTurns
```

## State tối thiểu Agent được đọc

```json
{
  "nodes": [{ "index": 0, "type": "sand", "starfish": 0 }],
  "nodeCount": 8,
  "selectedNodeIndex": null,
  "direction": null,
  "previewRoute": [],
  "stopIndex": null,
  "captureCandidates": [],
  "wetPitRescues": [],
  "finalTideSweepAvailable": false,
  "currentRedirects": [],
  "turnsUsed": 0,
  "optimalTurns": 0,
  "maxTurns": 0,
  "remainingStarfish": 0,
  "legalMoves": [],
  "rating": 0,
  "levelStatus": "playing"
}
```

Field thực tế do runtime cung cấp có thể khác tên; Agent không tự bổ sung field còn thiếu và không dùng memory thay cho state.

## Guardrails cho mọi Agent

- Rule Analyzer là nguồn duy nhất xác định legal move, preview, STOP, rescue event, Full Rescue và rating.
- Agent chỉ giải thích state hoặc chọn UI cue đã được cho phép.
- Agent không tự sow, capture, Sweep, thêm lượt, thêm sao, đổi objective, đổi rating hoặc cứu hộ thay player.
- Hint không cung cấp full move sequence hoặc cam kết thắng chắc.
- Không gọi hồ trung tâm là Vùng Nước An Toàn hoặc gameplay node.
- Không gọi Wet pit là Xoáy; đây là hai đường rescue khác nhau.
- Khi state thiếu hoặc mâu thuẫn, dùng fallback trung tính và không suy đoán.