推箱子游戲技術解讀文檔

項目概述

本項目是一個基於Electron開發的經典推箱子游戲，適用於鴻蒙PC平台。推箱子游戲是一款益智解謎遊戲，玩家需要通過方向鍵控制角色將所有箱子推到目標位置上以完成關卡。

軟件工程--推箱子游戲_#遊戲

技術要點

1. Electron主進程與渲染進程架構

項目採用標準的Electron架構，通過主進程管理應用窗口和生命週期，渲染進程負責遊戲界面展示和邏輯處理。

// main.js 核心結構
const { app, BrowserWindow } = require('electron');

function createWindow() {
    mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        title: '推箱子游戲 - Electron for 鴻蒙PC項目實戰案例',
        webPreferences: {
            preload: path.join(__dirname, 'preload.js'),
            nodeIntegration: true,
            contextIsolation: false
        }
    });

    mainWindow.loadFile('index.html');
}

2. 遊戲狀態管理與數據結構

遊戲採用對象化的狀態管理方式，通過gameState對象集中管理遊戲數據，包括當前關卡、棋盤狀態、玩家位置、移動次數等信息。

// 遊戲狀態管理
let gameState = {
    level: 0,
    board: [],
    player: { x: 0, y: 0 },
    moves: 0,
    history: [],
    levels: [],
    hints: 0
};

3. 遊戲核心算法

3.1 棋盤渲染與狀態表示

採用二維數組表示棋盤狀態，每個單元格使用不同的數值表示不同類型的元素：

// 遊戲常量定義
const WALL = 1;
const FLOOR = 0;
const TARGET = 2;
const BOX = 3;
const BOX_ON_TARGET = 4;
const PLAYER = 5;
const PLAYER_ON_TARGET = 6;
3.2 移動邏輯與碰撞檢測

移動算法需要處理玩家移動、箱子推動以及邊界檢測等情況：

// 移動玩家核心邏輯
function movePlayer(dx, dy) {
    // 檢查新位置是否有效
    // 處理不同類型的目標單元格
    // 更新遊戲狀態
    // 檢查遊戲勝利條件
}
3.3 撤銷功能實現

通過保存遊戲狀態歷史記錄，實現遊戲的撤銷功能：

// 保存遊戲狀態用於撤銷
function saveState() {
    gameState.history.push({
        board: JSON.parse(JSON.stringify(gameState.board)),
        player: { ...gameState.player },
        moves: gameState.moves
    });
}

4. 用户交互與響應式設計

項目實現了多種用户交互方式，包括鍵盤控制、按鈕點擊和鼠標點擊棋盤等，同時支持響應式設計以適應不同屏幕尺寸。

// 鍵盤控制實現
function handleKeyPress(event) {
    switch (event.key) {
        case 'ArrowUp': case 'w': case 'W':
            movePlayer(0, -1); // 上
            break;
        case 'ArrowRight': case 'd': case 'D':
            movePlayer(1, 0); // 右
            break;
        // 其他方向鍵和快捷鍵處理
    }
}

5. 關卡設計與管理

項目內置了多個難度遞增的關卡，通過數組存儲關卡數據，實現關卡的切換和管理：

// 關卡數據結構
{
    board: [
        [1, 1, 1, 1, 1, 1, 1],
        [1, 0, 0, 0, 0, 0, 1],
        // 更多行...
    ],
    player: { x: 3, y: 3 }
}

主要功能

  1. 多關卡支持：內置多個難度遞增的關卡
  2. 完整的遊戲操作：支持方向鍵、WASD和鼠標點擊移動
  3. 遊戲狀態記錄：顯示移動次數、當前關卡和遊戲狀態
  4. 撤銷功能：可以撤銷上一步操作
  5. 提示功能：在困難時提供遊戲提示
  6. 勝利檢測與慶祝：自動檢測勝利條件並顯示慶祝動畫
  7. 響應式UI：適配不同屏幕尺寸

項目結構

26-sokoban/
├── main.js          # Electron主進程
├── preload.js       # 預加載腳本
├── index.html       # 遊戲界面
├── style.css        # 樣式文件
├── renderer.js      # 遊戲邏輯
├── package.json     # 項目配置
└── README.md        # 技術文檔

實現細節

1. 遊戲初始化流程

遊戲初始化包括加載關卡數據、設置事件監聽器、初始化UI組件等步驟：

function initGame() {
    // 獲取DOM元素引用
    // 加載遊戲關卡
    // 添加事件監聽器
    // 初始化關卡選擇器
    // 加載第一關
}

2. 棋盤渲染機制

棋盤渲染採用動態創建DOM元素的方式，根據二維數組中的數值設置不同的樣式和元素：

function renderBoard() {
    // 清空棋盤
    // 設置棋盤網格樣式
    // 遍歷二維數組創建單元格
    // 根據單元格類型設置樣式和添加遊戲元素
}

3. 勝利檢測算法

勝利檢測通過遍歷整個棋盤，檢查是否所有箱子都位於目標點上：

function checkWin() {
    // 遍歷棋盤
    // 檢查是否還有箱子不在目標點上
    // 返回遊戲是否勝利
}

4. 提示系統實現

提示系統通過嘗試不同的移動方向，尋找可行的移動路徑：

function provideHint() {
    // 嘗試不同的移動方向
    // 尋找可行的移動
    // 高亮顯示提示位置
}

5. 響應式設計實現

通過CSS媒體查詢實現響應式設計，確保在不同屏幕尺寸下都有良好的遊戲體驗：

@media (max-width: 768px) {
    .game-container {
        padding: 16px;
    }
    
    .cell {
        width: 30px;
        height: 30px;
    }
    
    /* 更多響應式樣式 */
}

運行指南

  1. 安裝依賴：
npm install
  1. 啓動應用：
npm start
  1. 遊戲操作：
  • 使用方向鍵或WASD鍵移動玩家
  • 點擊棋盤上的相鄰單元格移動玩家
  • 點擊"重新開始"按鈕重新開始當前關卡
  • 點擊"撤銷"按鈕撤銷上一步操作
  • 點擊"提示"按鈕獲取遊戲提示

技術棧

  • Electron: ^29.0.0
  • HTML5/CSS3
  • JavaScript

優化與擴展方向

  1. 添加更多關卡：可以添加更多難度遞增的關卡
  2. 遊戲進度保存：使用Electron的存儲API保存遊戲進度
  3. 自定義關卡編輯器：允許用户創建和編輯自己的關卡
  4. AI求解器：實現自動求解功能，展示最優解決方案
  5. 遊戲音效：添加移動、推動箱子和勝利等音效
  6. 主題切換：支持明暗主題切換

鴻蒙PC適配改造指南

1. 環境準備

  • 系統要求：Windows 10/11、8GB RAM以上、20GB可用空間
  • 工具安裝：
    DevEco Studio 5.0+（安裝鴻蒙SDK API 20+）
  • Node.js 18.x+

2. 獲取Electron鴻蒙編譯產物

  1. 登錄Electron 鴻蒙官方倉庫
  2. 下載Electron 34+版本的Release包（.zip格式）
  3. 解壓到項目目錄，確認electron/libs/arm64-v8a/下包含核心.so庫

3. 部署應用代碼

將Electron應用代碼按以下目錄結構放置：

軟件工程--推箱子游戲_#遊戲_02

web_engine/src/main/resources/resfile/resources/app/
├── main.js
├── package.json
└── src/
    ├── index.html
    ├── preload.js
    ├── renderer.js
    └── style.css

4. 配置與運行

  1. 打開項目：在DevEco Studio中打開ohos_hap目錄
  2. 配置簽名：
    進入File → Project Structure → Signing Configs
  3. 自動生成調試簽名或導入已有簽名
  4. 連接設備：
    啓用鴻蒙設備開發者模式和USB調試
  5. 通過USB Type-C連接電腦
  6. 編譯運行：點擊Run按鈕或按Shift+F10

5. 驗證檢查項

  • ✅ 應用窗口正常顯示
  • ✅ 窗口大小可調整，響應式佈局生效
  • ✅ 控制枱無"SysCap不匹配"或"找不到.so文件"錯誤
  • ✅ 動畫效果正常播放

跨平台兼容性

平台

適配策略

特殊處理

Windows

標準Electron運行

無特殊配置

macOS

標準Electron運行

保留dock圖標激活邏輯

Linux

標準Electron運行

確保系統依賴庫完整

鴻蒙PC

通過Electron鴻蒙適配層

禁用硬件加速，使用特定目錄結構

鴻蒙開發調試技巧

1. 日誌查看

在DevEco Studio的Log面板中過濾"Electron"關鍵詞，查看應用運行日誌和錯誤信息。

2. 常見問題解決

  • "SysCap不匹配"錯誤：檢查module.json5中的reqSysCapabilities，只保留必要系統能力
  • "找不到.so文件"錯誤：確認arm64-v8a目錄下四個核心庫文件完整
  • 窗口不顯示：在main.js中添加app.disableHardwareAcceleration()
  • 動畫卡頓：簡化CSS動畫效果，減少重繪頻率項目展示瞭如何使用Electron開發桌面遊戲應用，以及如何將傳統遊戲邏輯與現代Web技術相結合。