使用 VuePress 來做個俄羅斯方塊攻略

大家好,我是卡米哥。今天要教大家怎麼用 VuePress 來做這個俄羅斯方塊攻略網站:https://etrex.tw/Vuepress-Demo/

本篇文章架構如下:

  • VuePress 簡介
  • Markdown 簡介
  • VuePress 安裝
  • VuePress 試用
  • Markdown-It 簡介
  • Markdown-It-Plugin 簡介
  • Markdown-It-Tetris
  • 在 VuePress 安裝 Markdown-It-Tetris
  • 設定 VuePress Style
  • 實際撰寫攻略
  • GitHub 簡介
  • GitHub Pages 簡介
  • 發布至 GitHub Pages

VuePress 簡介

VuePress 是一個靜態網站產生器,使用 Markdown 來撰寫文章,適合用來做簡單的部落格。他的特色是產生出來的靜態網站具有 SPA(單頁式網站)架構。

Markdown 簡介

因為寫 HTML 要打很多字很麻煩,所以世界上有了 Markdown,Markdown 好棒棒。

Markdown 是一種標記式語言,或者簡單的說就是一種文字檔的格式,其副檔名為 .md,可以很輕易的透過 Markdown Parser 將 .md 轉換為 .html 或者其他格式的內容。

VuePress 安裝

在 Terminal 輸入以下指令即可安裝 VuePress。

npm install -g vuepress

如果你不曉得怎麼操作 Terminal,可以參考龍哥的Git 教學:終端機及常用指令介紹

如果輸入指令後看到以下訊息,代表你還沒有安裝 node.js,請至 nodejs.org 安裝。

command not found: npm

如果成功的話會需要等一下,安裝 VuePress 需要一點時間。

VuePress 試用

以下是建立一個新的 VuePress 專案的流程:

  • 找一個空資料夾作為你的專案資料夾
  • 新增資料夾 docs
  • 新增文件 docs/README.md
  • 新增檔案 package.json
  • 建立 package.json 檔案

找一個空資料夾作為你的專案資料夾

首先建立一個空資料夾作為專案資料夾

新增資料夾 docs

在專案資料夾下新增一個名為 docs 的資料夾

新增文件 docs/README.md

docs 資料夾新增一個名為 README.md 的檔案,並且輸入以下文字:

# 網站目錄

- [VuePress 簡介](https://vuepress.vuejs.org)
- [Markdown 簡介](https://markdown.tw/)
- [Puyo Puyo Tetris 簡介](https://store.steampowered.com/app/546050/Puyo_PuyoTetris/)
- [DT Cannon 攻略](/dt_cannon.md)

Markdown 好棒棒

這個語法就是 Markdown 語法,詳細語法請參考 Markdown 簡介,以上僅示範最重要的標題、超連結、清單的部分。

新增檔案 package.json

在專案資料夾下新增一個名為 package.json 的檔案,並且輸入以下文字:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

執行 VuePress

在專案資料夾下的 Termainal 輸入以下指令來做測試:

npm run docs:dev

成功時會看到以下訊息,代表目前架好了一個網站,而且正在運行。

 DONE  [17:06:51] Build d96bf4 finished in 6292 ms!

> VuePress dev server listening at http://localhost:8080/

這時候可以到瀏覽器的網址列輸入 http://localhost:8080/ 來查看網站。如果想要關掉網站,在 Windows 可以至 Terminal 輸入 Ctrl + C,如果是 MacOS 請輸入 Command + C

Markdown-It 簡介

若想要將 Markdown 格式轉換為 HTML,需要用到 Markdown Parser,在這個世界上有許多款 Markdown Parser,而 Markdown-It 是其中一款。而我們使用的 Vuepress,正是採用 Markdown-It 作為 Markdown Parser。

Markdown-It-Plugin 簡介

Markdown 支援的語法很豐富,包含標題、清單、超連結、圖片、分隔線、程式碼區塊、引言區塊、表格等。但透過 Plugin,我們可以擴充 Markdown 的功能,讓它更加豐富,像是支援 Letax、emoji、各式圖表等的顯示,都能夠透過 Markdown Plugin 來達成。你也可以寫一個自己的 Markdown-It-Plugin 來定義自己的 Markdown 語法,以及轉換後的 HTML 內容。

Markdown-It-Tetris

神奇的是竟然有人閒到做了一個 Markdown-It-Plugin 專門用來顯示俄羅斯方塊盤面:Markdown-It-Tetris

如果你在 Markdown 中輸入以下內容:

tetris{

    t
   ttti
    ssizz
oo sslijzz
oo lllijjj
}

透過 Markdown-It-Tetris,將會被轉換為以下 HTML:

<div class="tetris">
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-t"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-t"></span>
<span class="tetris-t"></span>
<span class="tetris-t"></span>
<span class="tetris-i"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-empty"></span>
<span class="tetris-s"></span>
<span class="tetris-s"></span>
<span class="tetris-i"></span>
<span class="tetris-z"></span>
<span class="tetris-z"></span>
<span class="tetris-empty"></span>
<br/>
<span class="tetris-o"></span>
<span class="tetris-o"></span>
<span class="tetris-empty"></span>
<span class="tetris-s"></span>
<span class="tetris-s"></span>
<span class="tetris-l"></span>
<span class="tetris-i"></span>
<span class="tetris-j"></span>
<span class="tetris-z"></span>
<span class="tetris-z"></span>
<br/>
<span class="tetris-o"></span>
<span class="tetris-o"></span>
<span class="tetris-empty"></span>
<span class="tetris-l"></span>
<span class="tetris-l"></span>
<span class="tetris-l"></span>
<span class="tetris-i"></span>
<span class="tetris-j"></span>
<span class="tetris-j"></span>
<span class="tetris-j"></span>
</div>

這段 HTML 是需要搭配對應的 CSS 來呈現,如果單純就這段 HTML,在任何一個瀏覽器上看起來是都會是完全空白的畫面。

接下來說明如何在 VuePress 安裝 Markdown-It-Tetris,以及如何在 VuePress 上寫 CSS。

在 VuePress 安裝 Markdown-It-Tetris

安裝 Markdown-It-Tetris 到 VuePress 有兩個步驟:

  • 安裝 Markdown-It-Tetris
  • 在 VuePress 指定使用 Markdown-It-Tetris

安裝 Markdown-It-Tetris

在專案資料夾下的 Termainal 輸入以下指令:

npm install markdown-it-tetris --save

這段指令的意思是將 Markdown-It-Tetris 安裝到你的專案上。

在 VuePress 指定使用 Markdown-It-Tetris

docs 資料夾下建立一個名為 .vuepress 的資料夾,再到 .vuepress 資料夾下建立一個名為 config.js 的檔案,並且輸入以下內容:

module.exports = {
  title: '使用 VuePress 來做個俄羅斯方塊攻略',
  markdown: {
    config: md => {
      md.use(require('markdown-it-tetris'))
    }
  }
}

config.js 是設定檔,用來設定 VuePress 的一些參數,而我們設定的內容是指定要在 Markdown 當中使用 Markdown-It-Tetris。

設定 VuePress Style

現在我們要幫 Markdown-It-Tetris 產生出來的 HTML 加上一點顏色。到 .vuepress 資料夾下建立一個名為 style.styl 的檔案,並且輸入以下內容:

.tetris{
  background-color: black;
  border: 10px solid #333333;
  display: inline-block;
  font-size: 0px;
}
.tetris span{
  display: inline-block;
  width: 20px;
  height: 20px;
}
.tetris-t{
  background-color: rgb(142, 0, 207);
}
.tetris-z{
  background-color: #f00;
}
.tetris-i{
  background-color: rgb(0, 197, 197);
}
.tetris-s{
  background-color: rgb(17, 146, 0);
}
.tetris-o{
  background-color: rgb(255, 238, 0);
}
.tetris-j{
  background-color: rgb(0, 17, 255);
}
.tetris-l{
  background-color: rgb(255, 123, 0);
}
.tetris-g{
  background-color: rgb(80, 80, 80);
}

這樣就完成了。

實際撰寫攻略

docs 資料夾新增一個名為 dt_cannon.md 的檔案,並且輸入以下文字(文長):

## Puyo Puyo Tetris 簡介

[Puyo Puyo Tetris](https://store.steampowered.com/app/546050/Puyo_PuyoTetris/) 是一款支援多人對戰的魔法氣泡以及俄羅斯方塊混戰的遊戲,遊戲目標就是把對手堆高高。在各大平台上都有上架。推薦購買的版本是 Steam 版。

## 攻擊計算
在這款遊戲中的俄羅斯方塊如果消除時滿足某些條件,就能攻擊對手,造成對方的場地出現一些垃圾方塊,以下將大致說明:

- Tetris:一次消除 4 層,可讓對手增高 4 層
- T-Spin Double:利用 T-Spin 達成一次消除 2 層,可讓對手增高 4 層
- T-Spin Triple:利用 T-Spin 達成一次消除 3 層,可讓對手增高 6 層
- Back To Back:只使用 Tetris 以及 T-Spin 來做消除,可讓對手額外增高 1 層
- Combo:連續消除,可讓對手額外增高 1 層以上
- Perfect Clear:完全消除自己盤面上的所有方塊,可讓對手額外增高 10 層

詳細說明請參考 [harddrop](http://harddrop.com/wiki/Puyo_Puyo_Tetris#Tetris_vs_Tetris_.28Versus.29)。

所謂的 T-Spin 是指利用 T 方塊在特定的位置上旋轉,使 T 方塊抵達一個正常情況下無法抵達的位置。遊戲的設計者鼓勵大家多使用這種特殊技巧來做消除。

## 方塊旋轉系統
在俄羅斯方塊遊戲中,如果一個方塊的周圍沒有足夠大的空間放置旋轉後的方塊,就會卡住而無法旋轉。而方塊旋轉系統定義了什麼情況下可以旋轉,什麼情況下無法旋轉。近代的俄羅斯方塊由於 [The Tetris Company](https://en.wikipedia.org/wiki/The_Tetris_Company) 明文規定了[俄羅斯方塊遊戲實作指南](http://harddrop.com/wiki/Tetris_Guideline),俄羅斯方塊遊戲必須採用 [Super Rotation System(SRS)方塊旋轉系統](http://harddrop.com/wiki/SRS)。在了解 SRS 方塊旋轉系統後,你就能知道什麼情況下 T-Spin 是可以成功的。

## 方塊序列生成器
在俄羅斯方塊遊戲當中,方塊總共有 7 種(I, J, L, O, S, T, Z),而方塊的生成並不一定是完全隨機的,有一種方塊序列生成器叫做 7 bag,7 bag 是每次生成一組 7 種方塊並且打亂排序,在 7 bag 的系統中你可以預期方塊的出現數量是絕對平均的,大多數近代的俄羅斯方塊對戰遊戲都有實作 7 bag,由於方塊的序列是可預期的,所以就能在遊戲開始之前,就預先設想好盤面的佈置。

## DT Cannon 簡介
DT Cannon 是一個非常知名的起手式,一套完整的 DT Cannon 攻擊,可以使對手在一瞬間增高 12 層,其實整個遊戲也只有 20 層而已。

DT Cannon 就是如此兇狠致命的招。

一個經典的 DT Cannon 是由三個 bag 所組成,其中第一個 bag 的配置如下:

tetris {

    t
   ttti
    ssizz
oo sslijzz
oo lllijjj
}

第二個 bag 的配置如下:

tetris {

  lls  z
   lsszz i
jj lgszooi
j  ggggooi
j   gggggi
gg ggggggg
gg ggggggg
}

由於我們需要使用兩個 T 方塊來進行連續消除,而第一個 bag 已經使用了一個 T,第二個 bag 的 T 我們儲存在 Hold,並且等待第三個 bag 中的 T 方塊的到來,就能發動攻擊了。

第一個 T 的進入方式如下:

tetris {

t
ttggg  g
t  ggggg g
gg ggggggg
g  ggggggg
g   gggggg
gg ggggggg
gg ggggggg
}

在此處逆時針旋轉方塊 2 次

tetris {


 tggg  g
tttggggg g
gg ggggggg
g  ggggggg
g   gggggg
gg ggggggg
gg ggggggg
}

tetris {


  ggg  g
   ggggg g
ggtggggggg
gttggggggg
g t gggggg
gg ggggggg
gg ggggggg
}

等待方塊往下

tetris {


  ggg  g
   ggggg g
gg ggggggg
g tggggggg
gtt gggggg
ggtggggggg
gg ggggggg
}

再次逆時針旋轉方塊

tetris {


  ggg  g
   ggggg g
gg ggggggg
g  ggggggg
gtttgggggg
ggtggggggg
gg ggggggg
}

消除後

tetris {


  ggg  g
   ggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

此次消除造成 4 層傷害。

第二個 T 的進入方式如下:

tetris {

t
ttggg  g
t  ggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

在此處逆時針旋轉方塊 2 次

tetris {


 tggg  g
tttggggg g
gg ggggggg
g  ggggggg
gg ggggggg
}

tetris {


  ggg  g
   ggggg g
ggtggggggg
gttggggggg
ggtggggggg
}

消除後

tetris {


  ggg  g
   ggggg g
}

此次消除造成 8 層傷害。

不是所有的起手順序都能採用以上的配置,但這是一個有很高機率可以成功的起手配置,請參考[更多的 DT Cannon Pattern](http://harddrop.com/wiki/Double_Triple_Cannon_Setups)

現在可以重新執行 VuePress 並且進入首頁,最下面那個連結點進去就可以看到攻略囉!

GitHub 簡介

GitHub 是一個存放程式碼的網站,你可以將你的程式碼免費的存放到 GitHub 上,供大家觀賞。

將程式碼放到 GitHub 的方法是使用 Git,關於 Git 的使用,請參考龍哥的為你自己學 Git

GitHub Pages 簡介

如果想要讓網站發布到網路上,而不是只能在自己的電腦上看的話,需要找到一台電腦並且維持連網的狀態,把我們的網站放到這台電腦上。

GitHub Pages 就提供了這樣的功能,如果一個專案放到 GitHub 上,並且滿足 GitHub Pages 的規格,那麼 GitHub Pages 就允許你用瀏覽器輸入網址進入網站本體,而不是只能看到程式碼。

發布至 GitHub Pages

現在我們要將我們的 VuePress 專案的內容發布成一個靜態網站的資料夾,再將這個靜態網站發布到 GitHub 上,並且在 GitHub 做一些設定值上的調整,變成一個實際發布在網路上的網站囉!

在產生靜態網站之前,我們必須先在 VuePress 設定好與 GitHub Pages 搭配的基礎路徑,其基礎路徑必須與 GitHub Repository 的名稱相同。

基礎路徑的設定是透過修改 docs/.vuepress/config.js 來完成。我預計使用 Vuepress-Demo 作為我的 GitHub Repository 名稱。

module.exports = {
  title: '使用 VuePress 來做個俄羅斯方塊攻略',
  markdown: {
    config: md => {
      md.use(require('markdown-it-tetris'))
    }
  },
  base: "/Vuepress-Demo/"
}

加入了基礎路徑後,原本的首頁將會從 http://localhost:8080/ 進入,變成從 http://localhost:8080/Vuepress-Demo/ 進入。

產生靜態網站

在專案資料夾下的 Terminal 輸入以下指令:

npm run docs:build

成功後你會發現在 docs/.vuepress 資料夾下多了一個資料夾,叫做 dist

而在 dist 資料夾裡面有一個 index.html,這就是我們生成出來的靜態網站的首頁。 我們要把在 dist 資料夾下的所有檔案都上傳到 GitHub 上。

上傳程式碼到 GitHub

如果你還沒有 GitHub 的帳號和專案,你需要先登入 GitHub,並且建立一個新的 repository,以下假設你新建的 Repository 名為 Vuepress-Demo。

在專案資料夾下的 Terminal 輸入以下指令,即可上傳程式碼:

# 切換至專案資料夾
cd docs/.vuepress/dist

# 將程式碼加入 Git 管理
git init
git add -A
git commit -m 'deploy'

# 上傳至 GitHub
git push -f https://github.com/etrex/Vuepress-Demo.git master

其中,你會需要修改一下網址的部分,以及你可能會遇到需要在 Terminal 登入 github。

設定 GitHub Pages

到 GitHub 專案的設定頁,以我的為例,網址如下:https://github.com/etrex/Vuepress-Demo/settings

這個頁面很長,直接往下找到 GitHub Pages 的部分,你會看到一段文字:

Source
GitHub Pages is currently disabled. Select a source below to enable GitHub Pages for this repository. Learn more.

有個選擇 Source 的下拉式選單在這段文字的下方處,預設是選在 None,改為選擇 master branch 就完成了,完成後再次查看 GitHub Pages 的部分,會發現一個超連結指向我們做好的網站!

如果你點擊超連結後看到的是 GitHub Pages 的 404 網頁,請稍等個十分鐘再嘗試。如果還是沒有看見網站,請檢查你的 Repository 資料夾結構是否與我做出來的示範 Repository 相同。

那麼今天的教學就到這邊。