Mouse tracking and parallax

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

• Read mouse coordinates in the correct coordinate space.
• Scale layers to avoid exposed edges.
• Disable or replace mouse effects on touch platforms.

Core syntax

• renpy.get_mouse_pos
• ATL function
• parallax
• hover
• renpy.variant

Runnable example

init python:
    def make_parallax(strength_x, strength_y):
        # 返回一个 (trans, st, at) 函数；每帧根据鼠标位置设置偏移
        def f(trans, st, at):
            mx, my = renpy.get_mouse_pos()
            w = float(config.screen_width)
            h = float(config.screen_height)
            # 把鼠标位置归一化到 [-1, 1]，屏幕中心为 0
            nx = (mx / w) * 2 - 1
            ny = (my / h) * 2 - 1
            # 反向偏移更像“视差”（鼠标右移、背景左移）
            trans.xoffset = -nx * strength_x
            trans.yoffset = -ny * strength_y
            return 0          # 每帧调用
        return f

# 不同图层给不同强度：越靠前的层动得越多
transform parallax_bg:
    function make_parallax(15, 8)

transform parallax_mid:
    function make_parallax(35, 18)

transform parallax_fg:
    function make_parallax(70, 36)

Study outline

• Start with the smallest example for mouse tracking and parallax.
• Test the key terms in a clean Ren'Py project: renpy.get_mouse_pos, ATL function, parallax, hover.
• 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 ATL reference: https://www.renpy.org/doc/html/atl.html
• Ren'Py official reference: https://www.renpy.org/doc/html/other.html

How this fits in GenPy

• Use GenPy to keep effect scripts organized, then verify desktop and web behavior in Ren'Py.
• Document mobile fallbacks before publishing.

Recommended GenPy docs:

• Code editor
• Performance Editor
• Export and download