行空板K10弹珠迷宫Python版教程

行空板 K10 弹珠迷宫

一、项目背景

原项目是 DFRobot 社区上一篇弹珠迷宫教程：用一块带屏幕和三轴加速度计的小型开发板，做一个"靠倾斜板子控制弹珠滚出迷宫"的掌上小游戏。原方案硬件是 Stick S3，开发方式是 Arduino C++。

硬件平台

行空板 K10 是一块高度集成的 ESP32-S3 教学板，本项目用到的资源全部是板载的，没有外接任何一个元件：

二、功能介绍

玩法

倾斜板子，靠"重力"让金色弹珠在迷宫里滚动，滚进右上角的红色终点即通关。计时从开局开始，用时越短越好。

功能

状态

程序有三个状态，由 A 键驱动流转：

A键(开始)             到达终点
  [菜单页] ──────────> [游戏中] ──────────> [胜利页]
     ^                    |                    |
     |                    | A键(换图)          | A键
     └────────────────────┘                    └──> [菜单页]

  B键：在菜单页/游戏页随时循环切换方向模式（1→2→3→4→1）

三、硬件清单

本项目没有外接传感器、没有杜邦线——弹珠是画在屏幕上的虚拟小球，重力是板载加速度计的读数。

四、程序编写

整体结构

源码 15_marble_maze.py 共 8 个模块：

配置区

SCREEN_DIR = 2                 # 2 = 竖屏 240x320
MAZE_COLS = 15                 # 列数(必须奇数)
MAZE_ROWS = 17                 # 行数(必须奇数)
CELL = 16                      # 每格像素
TOP_BAR = 20                   # 顶部信息栏高度(容纳16号字)
MAZE_Y0 = TOP_BAR
FOOT_Y   = TOP_BAR + MAZE_H    # 底部提示区起始 y (290)
BALL_R = 5                     # 弹珠半径(像素)

迷宫生成

def gen_maze(cols, rows):
    """随机深度优先(DFS)生成完美迷宫。返回 bytearray, 1=墙 0=路。"""
    g = bytearray([1] * (cols * rows))
    stack = [(1, 1)]
    g[1 * cols + 1] = 0
    dirs = [(0, 2), (0, -2), (2, 0), (-2, 0)]
    while stack:
        cr, cc = stack[-1]
        d = shuffle4(list(dirs))
        moved = False
        for dr, dc in d:
            nr, nc = cr + dr, cc + dc
            if 0 < nr < rows - 1 and 0 < nc < cols - 1 and g[nr * cols + nc] == 1:
                g[((cr + nr) // 2) * cols + (cc + nc) // 2] = 0   # 打通中间墙
                g[nr * cols + nc] = 0
                stack.append((nr, nc))
                moved = True
                break
        if not moved:
            stack.pop()
    return g

说明：

• 先把整张图填成墙（全 1），然后从 (1,1) 开始"挖洞"。
• 用 bytearray 而不是 list：255 个格子只占 255 字节，ESP32 内存吃紧，这很重要。

从倾斜到移动

def update_ball():
    global bx, by, vx, vy, moves
    ax = (acce.read_x() - bias_x) * X_DIR
    ay = (acce.read_y() - bias_y) * Y_DIR

    # 死区
    if abs(ax) < DEADZONE:
        ax = 0.0
    else:
        ax = ax - DEADZONE if ax > 0 else ax + DEADZONE

    # 加速度 -> 速度, 再摩擦衰减
    vx = (vx + ax * ACCEL_SCALE) * FRICTION
    vy = (vy + ay * ACCEL_SCALE) * FRICTION
    # ... 限速 ...

# ---- X 轴移动 + 碰撞 ----
    if abs(vx) > 0.03:
        nx = bx + vx
        ex = nx + BALL_R if vx > 0 else nx - BALL_R     # 检测边缘点
        ec = int(ex) // CELL
        er = int(by - MAZE_Y0) // CELL
        if wall_at(ec, er):
            nx = (ec * CELL - BALL_R - 1) if vx > 0 else ((ec + 1) * CELL + BALL_R + 1)
            vx = 0.0
            sfx_bump()
        bx = nx

最后判断终点：

bc = int(bx) // CELL
    br = int(by - MAZE_Y0) // CELL
    return bc == goal_c and br == goal_r

六、遇到的问题与解决办法

硬件清单

• 行空板K10 MicroPython编程AI教学/学习主控板（含两头PH2.0白色硅胶线）- 蘑菇云科创教育1

• 弹珠通关.rar