Minigame Interface
The minigame interface exists to let one integrate non-visual-novel segments into Ren'Py games. It's expected that minigame creators will be comfortable programming in Python. The minigame interface provides a documented and supported set of functions the programmer can use to access the functionality needed to create minigames. The minigame interface assumes a familiarity with pygame.
The minigame interface uses Ren'Py's built-in screen update management system. This system compares lists of blits between frames, to find the areas of the screen that have changed between frames. Only these areas are drawn. This makes it unnecessary to do such update management by hand. To ensure optimal peformance of this system, the same surfaces should be used for each frame. (This can often be accomplished by using Minigame.load_image, which uses Ren'Py's image cache.)
Ren'Py supports loading, saving, and rollback during minigames, unless the key/mouse bindings used are overridden by the minigame. Loads, saves, and rollback bring the user to the start of the minigame, or to a Ren'Py statement before the minigame.
Minigame Object
Function: renpy.Minigame( | render_callback, event_callback) |
Constructs a new Minigame object, using the given callbacks.
render_callback is called each time a frame is drawn. It is called with four arguments. The first is a Render object, into which the new frame should be drawn. The second is the frame time, in fractional seconds from some arbitrary point in time. Its return value is ignored.
event_callback is called to indicate that an event has occured. It is called once per event, with four parameters. The first is the event, a pygame event object. The second and third are the x and y coordinates of the mouse at the time of the event. The last is the time of the event, in seconds from the same arbitrary point in time used by the render_callback.
If the event callback returns a non-None value, then that value will be returned from the Minigame.run method. If it returns None, then the event is passed to other displayables. (And so can cause rollback, menu entry, full-screen toggling, and the like.) If it calls the Minigame.ignore_event method, then processing of the event is terminated.
Most events are standard pygame events. If an event is unknown, it should be passed to other displayables, unless it causes a timeout to occur.
Method: Minigame.run( | ) |
This is the function that is called by user code to run the minigame. It adds the minigame to the screen, and handles events until the event_callback returns a value. It then returns that value.
Method: Minigame.load_image( | image) |
This loads image, which may be a string image file name, or an image manipulator. The image is added to Ren'Py's image cache, which makes future loads of it fast. This returns a pygame.Surface object, which should not be mutated.
Method: Minigame.mutated_surface( | surf) |
This informs the screen update management system that the supplied pygame surface has been mutated. This should be called after create a new pygame surface, either directly or by using one of pygame's transformation functions.
Method: ( | Minigame.render_text(text, font, size, color, bold=False, italics=False, underline=False, antialias=True) |
This renders the given text to a pygame surface. A cache is used to ensure the same surface is created when rendering the same text in multiple frames.
text is the text to be rendered.
font is the name of the font to use.
size is the size of the text in pixels.
color is the color of the font, either as a string or an rgba tuple.
bold determines if the font is to be bolded.
italics determines if the font is to be italicized.
underline determines if the font is to be underlined.
antialias determines if the rendered text is to be antialiased.
Method: ( | Minigame.redraw() |
This can be called from the render or event callbacks. It causes a render to occur as soon as possible.
Method: Minigame.timeout( | seconds) |
This causes an event to be delivered before seconds seconds has elapsed. The nature of the event is undefined, but we do promise it will be delivered sometime between now and now+seconds. (Often, the event is one that we will have delivered anyway, like MOUSEMOTION.)
Method: Minigame.load( | filename) |
This uses the standard Ren'Py loader to return an open file-like object with the given filename. The standard loader performs a search through directories and archives while looking for the filename.
Method: Minigame.ignore_event( | ) |
Calling this method from the event callback will cause the current event to be ignored. (This method raises an exception, and will not return.)
Render Object
Right now, the render object is mostly undocumented. We will assert it has height and width fields, and the following methods:
Method: Render.blit( | surf, (x, y)) |
This draws the surface to the render at the given location from the upper-left corner. Once it has been blitted to a render, surf should not be mutated. (This is because the actual drawing to the screen occurs shortly after the render_callback exits.)