Skip to content

Commit 30273e8

Browse files
ShenMianShenMian
committed
feat: initial commit
0 parents  commit 30273e8

39 files changed

+4122
-0
lines changed

‎.github/workflows/deploy.yml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
env:
8+
CARGO_TERM_COLOR: always
9+
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: write
15+
concurrency:
16+
group: ${{ github.workflow }}-${{ github.ref }}
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Setup mdBook
22+
uses: peaceiris/actions-mdbook@v1
23+
with:
24+
mdbook-version: 'latest'
25+
26+
- name: Add mermaid support
27+
run: cargo install mdbook-mermaid
28+
29+
- name: Add Katex support
30+
run: cargo install mdbook-katex
31+
32+
- run: mdbook build
33+
34+
- name: Deploy
35+
uses: peaceiris/actions-gh-pages@v3
36+
if: ${{ github.ref == 'refs/heads/main' }}
37+
with:
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
publish_dir: ./book

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
book

‎LICENSE

Lines changed: 395 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# 推箱子教程
2+
3+
本文将描述如何实现一个推箱子 📦, 示例代码使用 Rust 语言 🦀 编写.
4+
5+
本文遵循 [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) 协议发布. 部分图片来源于互联网, 版权归原作者所有.

‎book.toml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[book]
2+
title = "推箱子教程"
3+
description = "本文将描述如何实现一个推箱子 📦, 示例代码使用 Rust 语言 🦀 编写."
4+
authors = ["ShenMian <sms_school@outlook.com>"]
5+
language = "zh-Hans-CN"
6+
multilingual = false
7+
src = "src"
8+
9+
[output.html]
10+
additional-js = ["mermaid.min.js", "mermaid-init.js"]
11+
git-repository-url = "https://github.com/ShenMian/sokoban-tutorial"
12+
git-repository-icon = "fa-github"
13+
14+
[preprocessor.mermaid]
15+
command = "mdbook-mermaid"
16+
17+
[preprocessor.katex]
18+
after = ["links"]

‎mermaid-init.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mermaid.initialize({ startOnLoad: true, theme: 'neutral' });

‎mermaid.min.js

Lines changed: 1648 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/SUMMARY.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Summary
2+
3+
[介绍](introduction.md)
4+
5+
- [关卡](level/README.md)
6+
- [表示](level/representation.md)
7+
- [构造](level/construction.md)
8+
- [标准化 🚧](level/normalization.md)
9+
- [动作]()
10+
- [求解器 🚧](solver/README.md)
11+
- [搜索策略 🚧](solver/solving_strategy.md)
12+
- [启发式函数 🚧](solver/heuristic_function.md)
13+
- [优化](solver/optimization.md)
14+
- [隧道]()
15+
- [死锁 🚧](solver/deadlocks.md)
16+
- [割点]()
17+
- [双向搜索 🚧](solver/bidirectional_search.md)
18+
- [特征]()
19+
- [优化器]()
20+
- [资源 🚧](resources.md)
21+
- [术语表 🚧](glossary_of_terms.md)

‎src/assets/boxworld_1.png

141 KB
Loading

‎src/assets/everyones_sokoban.jpg

93.4 KB
Loading

‎src/assets/first_sokoban_15.png

4.23 KB
Loading

‎src/assets/no_walls_level.png

159 KB
Loading

‎src/assets/sasquatch_41.png

219 KB
Loading

‎src/assets/steaming_hot.png

181 KB
Loading

‎src/glossary_of_terms.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# 术语表
2+
3+
| 中文 | 英文 |
4+
| ----------- | -------- |
5+
| 求解器 | solver |
6+
| 解决方案/解 | solution |
7+
| 动作 | action |

‎src/introduction.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# 介绍
2+
3+
本文将描述如何实现一个推箱子 📦, 示例代码使用 Rust 语言 🦀 编写.
4+
5+
## 推箱子的起源
6+
7+
推箱子在 1981 年由日本人今林宏行(いまばやし ひろゆき)所创造, 第一个版本于 1982 年 12 月发行, 名为*仓库番*, 字面意思为 "仓库管理员" 👷.[^1] 英文名为: Sokoban 或 Soukoban.
8+
9+
![First Sokoban #15](assets/first_sokoban_15.png)
10+
11+
截至 2024 年, 最新版本推箱子(みんなの倉庫番)于 2019 年 8 月发行于 PlayStation 4 平台.[^1]
12+
13+
![The Sokoban](assets/everyones_sokoban.jpg)
14+
15+
最新版本的推箱在角色控制方面相较于其最初的版本并未见明显改进, 本文后续将介绍一种纯鼠标控制的角色控制方法 🖱️.
16+
17+
## 为什么通过案例来讲解
18+
19+
本文以推箱子为案例, 深入浅出的描述软件开发过程. 通过案例讲解有以下目的:
20+
21+
- 结合实例的学习可以将**知识**和**应用**结合在一起, 使读者无需被 "学这个有什么用?" 所困扰 🤔.
22+
- 提供丰富的实例. 推箱子问题本身还附带了许多子问题, 很适合作为例子使用.
23+
- 众多读者对游戏有浓厚的兴趣 🎮.
24+
25+
## 为什么选择推箱子作为案例
26+
27+
之所以选择推箱子, 是因为它具有以下特点:
28+
29+
- **规则简单**: 可以专注于实现功能, 而非理解复杂的游戏规则和机制.
30+
- **基本功能易于实现**: 如推箱子和通关判断.
31+
- **有具有挑战的高级功能**: 如纯鼠标控制, 逆推等.
32+
- **有需要深入钻研的求解器**: 用于自动求解推箱子关卡.
33+
34+
推箱子的实现**既可以简单也可以复杂**, 读者可以根据自身的情况选择学习的深度.
35+
36+
## 需要具备的知识
37+
38+
- 具备 Rust 语言的语法基础, 或熟悉一门编程语言.
39+
- 有关高级功能和求解器的章节: 具备数据结构与算法的基础知识, 如 A* 搜索算法的工作原理.
40+
41+
## 内容范围
42+
43+
本文将描述基本功能的具体实现方法, 高级功能的实现方法以及求解器的实现思路.
44+
但本文**不涉及**以下内容:
45+
46+
- Rust 语言本身: 本文中出现的算法适用于其他编程语言, 但依然会涉及部分 Rust 相关内容的讲解, 如错误处理 (Rust 在这方面和其他语言不太一样), 不感兴趣的读者可以直接跳过这部分内容.
47+
- 游戏引擎: 本文中的推箱子实现并不依赖游戏引擎, 比如有的推箱子实现需要用到射线检测.
48+
- 推箱子的其他变体(Variant)[^2].
49+
50+
## 项目代码
51+
52+
完整的项目代码位于:
53+
54+
- [ShenMian/soukoban](https://github.com/shenmian/soukoban): 推箱子相关算法实现.
55+
- [ShenMian/sokoban-rs](https://github.com/shenmian/sokoban-rs): 推箱子实现, 使用 Bevy 引擎.
56+
57+
## 拓展资料
58+
59+
推荐视频 🎥:
60+
61+
- [【GM】火遍全球的推箱子，那些你所不知道的故事！· Bilibili](https://www.bilibili.com/video/BV1Ph41117YT): 该视频详细介绍了推箱子的历史和发展.
62+
63+
## 版权
64+
65+
本文遵循 [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) 协议发布. 部分图片来源于互联网, 版权归原作者所有.
66+
67+
[^1]: <https://www.sokoban.jp/history.html>
68+
[^2]: <https://en.wikipedia.org/wiki/Sokoban#Variants>

0 commit comments

Comments
 (0)