Custom Mouse Cursors link

Ren'Py has two systems for creating custom mouse cursors. The first takes advantage of the hardware mouse cursor, while the second uses Ren'Py to draw a displayable as the mouse cursor.

The hardware mouse cursor has the advantages:

  • It is very fast.
  • It is very low overhead, leaving Ren'Py time to do other things.

And the limitation:

  • Cursors are limited to small sizes. 32x32 is guaranteed, while 64x64 seems to work widely.
  • Cursors are limited to sequences of image files.

Using Ren'Py to draw a displayable as a cursor inverts these restrictions. While the cursors can be anything Ren'Py can draw, Ren'Py needs to do the drawing. When triple buffering is enabled on a computer, a lag can be present that isn't for the harware cursor.

Hardware Mouse Cursor link

The hardware cursor is controlled by the config.mouse variable. This variable consists of a dictionary, that maps mouse names to a list of frames. Each frame is a 3-component tuple that contains an image file, and then X and Y offsets within that image.

For example:

define config.mouse = { }
define config.mouse['default'] = [ ( "gui/arrow.png", 0, 0) ]
define config.mouse['spin' ] = [
    ( "gui/spin0.png", 7, 7 ),
    ( "gui/spin1.png", 7, 7 ),
    ( "gui/spin2.png", 7, 7 ),
    ( "gui/spin3.png", 7, 7 ),
    ( "gui/spin4.png", 7, 7 ),
    ( "gui/spin5.png", 7, 7 ),
    ( "gui/spin6.png", 7, 7 ),
    ( "gui/spin7.png", 7, 7 ),
]

When an animation consists of multiple frames, the frames are played back at 20fps. Ren'Py will only change the cursor when the image or offsets change.

Displayable Mouse Cursor link

A displayable cursor uses the config.mouse_displayable variable, and the MouseDisplayable displayable. As an example:

image "mouse spin":
    "gui/spin0.png"
    rotate 0.0
    linear 1.0 rotate 360.0

    # Pause so image prediction can happen.
    pause 1.0

    repeat

define config.mouse_displayable = MouseDisplayable(
    "gui/arrow.png", 0, 0).add("spin", "spin mouse", 9.9, 9.9)
MouseDisplayable(cursor, x, y) link

A displayable that wraps a mouse cursor displayable, and causes it to move across the screen when the player moves their mouse.

cursor
A displayable that is used to draw the mouse.
x, y
The coordinates of the hotspot, relative to the upper left corner of the mouse, in virtual pixels.

Using Mouse Cursors link

The usual way to use a mouse cursor is to provide the mouse property, giving the name of the cursor, to something that can be focused in a screen. (A button or bar.) For example:

screen test():
    textbutton "Mouse Test" action NullAction() mouse "spin"

It's also possible to use default_mouse to set the mouse cursor globally:

$ default_mouse = "spin"