自定义鼠标光标与拖尾

本页属于 GenPy Ren'Py 学习路线。教程内容面向 Ren'Py 8.x，并在页面末尾连接到 GenPy 的对应工作流。

学习目标

• 了解“自定义鼠标光标与拖尾”在 Ren'Py 项目中的用途。
• 能在一个最小项目里验证本章相关语法或工作流。
• 知道发布前需要检查的常见风险，并能在 GenPy 中继续维护。

核心语法

• config.mouse
• config.mouse_displayable
• MouseDisplayable
• cursor trail
• renpy.variant

可运行示例

init python:
    config.mouse = {
        # default 必须有，作为兜底
        "default": [ ("gui/cursor.png", 0, 0) ],
    }

教程正文

把系统默认箭头换成游戏专属光标，甚至做出会发光、有拖尾的鼠标——增强氛围与精致感。

1. 自定义光标（静态）

用 config.mouse 字典定义光标。值是一组 (图片, x热点, y热点) 帧；多帧即动画。

init python:
    config.mouse = {
        # default 必须有，作为兜底
        "default": [ ("gui/cursor.png", 0, 0) ],
    }

• (图片, xoffset, yoffset)：后两个是热点像素相对图片左上角的偏移 （即“真正点击的那个点”，箭头通常是 0,0；圆形光标常取中心）。
• 图片建议 ≤ 32×32（保证所有硬件可用），64×64 多数硬件可用，更大可能失效。

2. 动画光标（多帧）

一个 key 给多帧，按 20Hz 循环播放：

init python:
    config.mouse = {
        "default": [
            ("gui/cur0.png", 4, 4),
            ("gui/cur1.png", 4, 4),
            ("gui/cur2.png", 4, 4),
            ("gui/cur1.png", 4, 4),
        ],
    }

3. 情境光标（不同场合不同光标）

Ren'Py 在不同交互态会找不同的 key，找不到才回退 default。常用 key： default、say、with、menu、prompt、imagemap、button、pause、mainmenu、gamemenu。 还可加前缀 pressed_ 表示“按下时”的光标。

init python:
    config.mouse = {
        "default": [ ("gui/cursor.png", 0, 0) ],
        "button":  [ ("gui/cursor_hand.png", 6, 0) ],   # 悬停按钮变成手型
        "pressed_button": [ ("gui/cursor_grab.png", 6, 0) ],
    }

4. 跟随鼠标的光效（发光球/萤火）

想要“一个光点永远贴着鼠标飘”，用 ATL function 把图定位到鼠标坐标，叠在最上层：

init python:
    def follow_mouse(trans, st, at):
        mx, my = renpy.get_mouse_pos()
        trans.xpos = mx
        trans.ypos = my
        trans.xanchor = 0.5      # 让图中心对准鼠标
        trans.yanchor = 0.5
        return 0

transform cursor_glow:
    function follow_mouse
    # 叠加一点呼吸/旋转
    block:
        ease 1.0 alpha 0.6
        ease 1.0 alpha 1.0
        repeat

screen cursor_fx():
    zorder 100
    add "fx/glow.png" at cursor_glow      # 一个柔光 PNG

# 全局开启
label start:
    show screen cursor_fx
    "光点会一直跟着鼠标。"

5. 鼠标拖尾（Trail，进阶）

拖尾 = 记录最近若干个鼠标位置，沿途画一串逐渐变淡的图。用**自定义可显示物（CDD）**最稳：

init python:
    class MouseTrail(renpy.Displayable):
        def __init__(self, image, length=12, **kwargs):
            super(MouseTrail, self).__init__(**kwargs)
            self.image = Image(image)
            self.length = length          # 拖尾长度
            self.history = []             # 最近的鼠标位置

        def render(self, width, height, st, at):
            mx, my = renpy.get_mouse_pos()
            self.history.append((mx, my))
            while len(self.history) > self.length:
                self.history.pop(0)

            r = renpy.Render(width, height)
            base = renpy.render(self.image, width, height, st, at)
            iw, ih = base.get_size()

            n = len(self.history)
            for idx, (x, y) in enumerate(self.history):
                # 越新的点越不透明
                a = (idx + 1) / float(n)
                d = Transform(self.image, alpha=a)
                dr = renpy.render(d, width, height, st, at)
                r.blit(dr, (int(x - iw / 2), int(y - ih / 2)))

            renpy.redraw(self, 0)         # 请求下一帧，持续更新
            return r

image cursor_trail = MouseTrail("fx/spark.png", length=14)

screen cursor_trail_fx():
    zorder 100
    add "cursor_trail"

label start:
    show screen cursor_trail_fx
    "拖动鼠标，身后会拖出一串光点。"

这是逐帧 CDD，length 控制拖尾长短。点数别太多（10~20 足够），否则每帧渲染开销大。

6. 完全自绘光标（MouseDisplayable）

想隐藏系统光标、用一个完全自定义的可显示物当光标，用 config.mouse_displayable：

init python:
    config.mouse_displayable = MouseDisplayable("fx/glow.png", 16, 16)
    # 也可传一个返回可显示物的函数，按状态返回不同光标

它会隐藏系统光标并由该可显示物负责绘制“合成光标”，可与拖尾结合做出整套华丽光标。

常见坑

• config.mouse 的每个 key 值是帧列表，单帧也要写成 [(...)]。
• 热点偏移设错，会出现“点击位置和图标尖端对不上”。
• 跟随/拖尾要放在高 zorder 的屏幕（如 overlay/screens 层）才不被遮住。
• 移动端无鼠标；这些效果按 renpy.variant("touch") 关闭或换方案。
• 自定义光标图建议 PNG 透明背景，尺寸别超 64×64。

官方参考

• 自定义光标：https://www.renpy.org/doc/html/mouse.html
• config.mouse / config.mouse_displayable：https://www.renpy.org/doc/html/config.html
• 自定义可显示物：https://www.renpy.org/doc/html/cdd.html

在 GenPy 里怎么做

• 在 GenPy 的代码模式中维护相关 .rpy 文件，先保持语法清晰，再逐步加入本章功能。
• 用故事图谱、变量、校验或演出编辑器把“能运行”提升到“可维护”。
• 导出前结合 Ren'Py Lint 和 GenPy 校验结果，确认脚本、素材和发布路径一致。

推荐继续阅读：

• GUI 主题
• 屏幕编辑器
• 代码模式