Custom cursors and trails

This page is part of the GenPy Ren'Py learning path. It focuses on practical Ren'Py 8.x production and links each concept back to the GenPy workflow.

Learning goals

• Choose config.mouse for simple cursor swaps.
• Use mouse displayables only when necessary.
• Disable cursor effects on touch devices.

Core syntax

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

Runnable example

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

Study outline

• Start with the smallest example for custom cursors and trails.
• Test the key terms in a clean Ren'Py project: config.mouse, config.mouse_displayable, MouseDisplayable, cursor trail.
• Move the pattern back into your real project only after the example runs.
• Use GenPy docs and validation to keep the feature connected to story, assets, and export readiness.

Common pitfalls

• Test the smallest working script before layering on visual or UI complexity.
• Run Ren'Py Lint before release builds, even when the script appears to run locally.
• Keep examples in standard .rpy files so they remain editable outside GenPy.

Official references

• Ren'Py official reference: https://www.renpy.org/doc/html/mouse.html
• Ren'Py official reference: https://www.renpy.org/doc/html/config.html
• Ren'Py official reference: https://www.renpy.org/doc/html/cdd.html

How this fits in GenPy

• Keep cursor code isolated and test it in the exported runtime.
• Use GenPy docs to connect UI effects with broader GUI work.

Recommended GenPy docs:

• GUI Theme
• Screen Editor
• Code editor