Hexo 網頁寵物插件

2026年08月22日 1.8k 字大概 8 分鐘

在BLOG加一個煩人的小東西。

介紹

簡單說就是一個 Hexo 用的網頁小寵物。

不吃 Live2D 模型，直接吃幾張透明 PNG 圖片 (因為我不會做live 2d模型)。

目前基本動作有五個：

動作	用途
`idle`	預設站立
`sleep`	躺下或睡覺
`talk`	講話
`look`	仔細看文章內容
`dragged`	被拖曳時

另外還有一個可選動作：

動作	用途
`umbrella`	雨天備用動作

這邊注意：umbrella 不是每個角色都一定要有。
如果目前隨機載入的角色有設定 umbrella，而且頁面上偵測到下雨關鍵字，才會切成雨傘圖。
如果角色沒有這張圖，就會維持一般動作，不會破圖。

目前功能

大概整理一下目前有的功能：

載入新頁面時隨機挑選角色
所有角色圖片都可以從 config 設定
手機預設不顯示，避免擋到閱讀
滑鼠在角色左邊或右邊時，角色會轉向
右鍵快速點兩下可以拖曳角色
拖到視窗邊邊後會停駐，不再自己跑回文章中間
可以設定拖到邊邊後直接隱藏
會去找文章內的標題、圖片、程式碼區塊，偶爾走過去看一下
支援雨天關鍵字，角色有雨傘圖時會切換成雨傘動作

一開始只是想做一個小東西，後來想想如果只有我自己能改 JS 好像也不太方便，所以最後把大部分內容都拉到 _config.kira.yml 裡面。
這樣之後如果別人想換角色，不需要打開腳本，只要改圖片網址就好。

資料夾大概長這樣：

ROY-pet-plugin/
  scripts/
    ROY-pet.js
  source/
    js/
      ROY-pet.js
    pet/
      ROY/
        ROY-pet.css
        manifest.json
        idle/preview.png
        sleep/preview.png
        talk/preview.png
        look/preview.png
        dragged/preview.png
        umbrella/preview.png
        preview/index.html
        preview/preview.css
      ROY-black/
        idle/preview.png
        sleep/preview.png
        talk/preview.png
        look/preview.png
        dragged/preview.png
        preview/contact-sheet.png
  examples/
    _config.kira.yml
  README.md
  package.json

安裝方式

去 GitHub 把整個專案下載下來，然後把這幾個資料夾複製到自己的 Hexo 根目錄：

scripts/ROY-pet.js
source/js/ROY-pet.js
source/pet/ROY/
source/pet/ROY-black/

複製完後，自己的 Hexo 專案應該會像這樣：

your-hexo-blog/
  scripts/ROY-pet.js
  source/js/ROY-pet.js
  source/pet/ROY/
  source/pet/ROY-black/

接著把設定加到 _config.kira.yml 或你實際使用的主題 config 裡。

我這邊是 Kira 主題，所以放在：

1	`_config.kira.yml`

如果你的主題沒有使用 _config.kira.yml，那就放到 _config.yml 或主題自己的 config。

基本設定

下面是目前我自己使用的設定。

ROY_pet:
  enable: true  ### 是否開啟插件

  paths:
    script: /js/ROY-pet.js
    style: /pet/ROY/ROY-pet.css

  mobile:
    show: false   ### 手機瀏覽是某要開
    breakpoint: 700

  display:
    initial_position: left      ### 角色初始位置
    size: 124
    z_index: 40
    offset:
      x: 0
      y: 0

  characters:  ### 角色圖片、名稱等基本設定
    - id: ROY
      name: ROY
      enabled: true
      assets:
        idle: /pet/ROY/idle/preview.png
        sleep: /pet/ROY/sleep/preview.png
        talk: /pet/ROY/talk/preview.png
        look: /pet/ROY/look/preview.png
        dragged: /pet/ROY/dragged/preview.png
        umbrella: /pet/ROY/umbrella/preview.png
    - id: ROY_black
      name: BLACK_ROY
      enabled: true
      assets:
        idle: /pet/ROY-black/idle/preview.png
        sleep: /pet/ROY-black/sleep/preview.png
        talk: /pet/ROY-black/talk/preview.png
        look: /pet/ROY-black/look/preview.png
        dragged: /pet/ROY-black/dragged/preview.png

  behavior:  ### 角色行為
    click_to_drag_count: 2
    click_window_ms: 1200
    drag_button: right
    edge_park: true
    edge_dismiss: false
    edge_threshold: 36
    avoid_oml2d: true
    rain_detection: true
    follow_cursor: true
    cursor_follow_actions:
      - idle
      - look
      - talk

    initial_message: 我來了。   ### 角色會講的句子
    messages:
      drag_start: 嗚，被抓到了。
      drag_end: 我自己也會走啦。
      park: 我先待在旁邊。
      look_target: 這裡有東西。
    phrases:
      - 我在這裡。
      - 這段看起來值得多看一眼。
      - 今天也有好好寫筆記。
      - 讓我找個地方待一下。
      - 需要我陪你讀一段嗎？
    rain_words:
      - 雨
      - 下雨
      - 陣雨
      - 雷雨
      - 降雨
      - rain
      - shower
      - storm

每一個角色都需要有：

idle
sleep
talk
look
dragged

umbrella 可以有，也可以沒有。

新增角色

如果你要新增自己的角色，就在 source/pet/ 底下新增資料夾。

例如：

source/pet/my-character/
  idle/preview.png
  sleep/preview.png
  talk/preview.png
  look/preview.png
  dragged/preview.png
  umbrella/preview.png

然後 config 裡面加上：

characters:
  - id: my_character
    name: 我的角色
    enabled: true
    assets:
      idle: /pet/my-character/idle/preview.png
      sleep: /pet/my-character/sleep/preview.png
      talk: /pet/my-character/talk/preview.png
      look: /pet/my-character/look/preview.png
      dragged: /pet/my-character/dragged/preview.png
      umbrella: /pet/my-character/umbrella/preview.png

如果沒有雨傘圖，就把 umbrella 那行刪掉。

圖片規格建議：

PNG
透明背景
512 x 512 px
每個動作角色大小盡量一致

不然切換動作時會有忽大忽小的感覺。

初始位置設定

initial_position 使用九宮格概念。

可以填：

1
2
3

top-left, top, top-right,
left, center, right,
bottom-left, bottom, bottom-right

也可以填中文：

1	`左上、上、右上、左、中、右、左下、下、右下`

例如想讓角色一開始在左邊：

1 2	`display: initial_position: left`

想要調整大小：

1 2	`display: size: 124`

拖曳設定

目前預設是右鍵快速點兩下後拖曳。

behavior:
  click_to_drag_count: 2
  click_window_ms: 1200
  drag_button: right

drag_button 可以填：

1	`right, left, middle, any`

也可以用數字：

1
2
3

0 = 左鍵
1 = 中鍵
2 = 右鍵

會設成右鍵主要是避免一般點擊角色時太容易誤觸拖曳。

拖到邊邊停駐

這個是我覺得比較實用的功能。

有時候角色在文章中間走來走去，雖然可愛，但真的在看文章時可能會擋到內容。
所以我加了拖到邊邊後停駐的功能。

behavior:
  edge_park: true
  edge_dismiss: false
  edge_threshold: 36

edge_park: true 表示拖到視窗邊緣後停駐。
停駐後它不會再跑回文章中間，也不會再自己去看標題或圖片。
一直到換頁或重新整理才會恢復正常活動。

如果你想要拖到邊邊後直接消失，可以改成：

1	`edge_dismiss: true`

雨天偵測

rain_words 是雨天關鍵字。

rain_words:
  - 雨
  - 下雨
  - 陣雨
  - 雷雨
  - 降雨
  - rain
  - shower
  - storm

程式會去掃頁面上的天氣區塊或相關文字，如果命中這些字，就會把內部狀態當成雨天。

如果目前角色有 umbrella，就可能切成雨傘動作。
如果角色沒有 umbrella，就維持一般動作。

測試時也可以直接在瀏覽器 Console 輸入：

1	`localStorage.setItem('ROY:rain', '1')`

要取消測試：

1	`localStorage.removeItem('ROY:rain')`

手機顯示

手機預設是關掉的。

1
2
3

mobile:
  show: false
  breakpoint: 700

因為手機畫面本來就小，再放一個角色很容易擋到文章。
如果你真的想開，就改成：

1 2	`mobile: show: true`

預覽頁

插件裡面有放素材預覽頁：

1	`/pet/ROY/preview/`

這個頁面只會顯示圖片，不會啟動真正的網頁寵物。
主要是用來檢查角色動作有沒有破圖、大小有沒有差太多。

打包檢查

1	`npm run build`

最後

可以用AI幫你產好所有圖片比較方便，也不會耗多少token。
覺得麻煩就丟到視窗最右邊他就不會一直往前跑了。
可以有很多種圖片讓角色在畫面上到處跑。

本插件與素材主要用於個人 Blog 美化與學習紀錄，無任何商業利用。