Other Functions and Variables — Ren'Py Documentation

# Other Functions and Variables

We're in the process of migrating the documentation over to a new tool. As not every page has been migrated yet, this exists to document new functionality that has no other place to go.

`renpy.` `add_layer`(layer, above=None, below=None, menu_clear=True)

  Adds a new layer to the screen. If the layer already exists, this function does nothing.

  One of behind or above must be given.

  layer
    A string giving the name of the new layer to add.
  above
    If not None, a string giving the name of a layer the new layer will be placed above.
  below
    If not None, a string giving the name of a layer the new layer will be placed below.
  menu_clear
    If true, this layer will be cleared when entering the game menu context, and restored when leaving the

`renpy.` `add_python_directory`(path)

  Adds path to the list of paths searched for Python modules and packages. The path should be a string relative to the game directory. This must be called before an import statement.

`renpy.` `call_stack_depth`()

  Returns the depth of the call stack of the current context - the number of calls that have run without being returned from or popped from the call stack.

`renpy.` `choice_for_skipping`()

  Tells Ren'Py that a choice is coming up soon. This currently has two effects:

  - If Ren'Py is skipping, and the Skip After Choices preferences is set to stop skipping, skipping is terminated.
  - An auto-save is triggered.

`renpy.` `clear_game_runtime`()

  Resets the game runtime counter.

`renpy.` `clear_keymap_cache`()

  Clears the keymap cache. This allows changes to `config.keymap` to take effect without restarting Ren'Py.

`renpy.` `context_dynamic`(*vars)

  This can be given one or more variable names as arguments. This makes the variables dynamically scoped to the current context. The variables will be reset to their original value when the call returns.

  An example call is:

      $ renpy.context_dynamic("x", "y", "z")

`renpy.` `count_dialogue_blocks`()

  Returns the number of dialogue blocks in the game's original language.

`renpy.` `count_newly_seen_dialogue_blocks`()

  Returns the number of dialogue blocks the user has seen for the first time during this session.

`renpy.` `count_seen_dialogue_blocks`()

  Returns the number of dialogue blocks the user has seen in any play-through of the current game.

`renpy.` `dynamic`(*vars)

  This can be given one or more variable names as arguments. This makes the variables dynamically scoped to the current call. The variables will be reset to their original value when the call returns.

  An example call is:

      $ renpy.dynamic("x", "y", "z")

`renpy.` `focus_coordinates`()

  This attempts to find the coordinates of the currently-focused displayable. If it can, it will return them as a (x, y, w, h) tuple. If not, it will return a (None, None, None, None) tuple.

`renpy.` `force_autosave`(take_screenshot=False)

  Forces a background autosave to occur.

  take_screenshot
    If True, a new screenshot will be taken. If False, the existing screenshot will be used.

`renpy.` `force_full_redraw`()

  Forces the screen to be redrawn in full. Call this after using pygame to redraw the screen directly.

`renpy.` `free_memory`()

  Attempts to free some memory. Useful before running a renpygame-based minigame.

`renpy.` `full_restart`(transition=False, label='_invoke_main_menu', target='_main_menu')

  Causes Ren'Py to restart, returning the user to the main menu.

  transition
    If given, the transition to run, or None to not run a transition. False uses `config.end_game_transition`.

`renpy.` `get_adjustment`(bar_value)

  Given bar_value, a `BarValue`, returns the `ui.adjustment()` if uses. The adjustment has the following to attributes defined:

  `value`

    The current value of the bar.

  `range`

    The current range of the bar.

`renpy.` `get_autoreload`()

  Gets the autoreload flag.

`renpy.` `get_game_runtime`()

  Returns the game runtime counter.

  The game runtime counter counts the number of seconds that have elapsed while waiting for user input in the top-level context. (It does not count time spent in the main or game menus.)

`renpy.` `get_image_load_log`(age=None)

  A generator that yields a log of image loading activity. For the last 100 image loads, this returns:

  - The time the image was loaded (in seconds since the epoch).
  - The filename of the image that was loaded.
  - A boolean that is true if the image was preloaded, and false if the game stalled to load it.

  The entries are ordered from newest to oldest.

  age
    If not None, only images that have been loaded in the past age seconds are included.

  The image load log is only kept if config.developer = True.

`renpy.` `get_mouse_pos`()

  Returns an (x, y) tuple giving the location of the mouse pointer or the current touch location. If the device does not support a mouse and is not currently being touched, x and y are numbers, but not meaningful.

`renpy.` `get_physical_size`()

  Returns the size of the physical window.

`renpy.` `get_refresh_rate`(precision=5)

  Returns the refresh rate of the current screen, as a floating-point number of frames per second.

  precision

    The raw data Ren'Py gets is number of frames per second, rounded down. This means that a monitor that runs at 59.95 frames per second will be reported at 59 fps. The precision argument reduces the precision of this reading, such that the only valid readings are multiples of the precision.

    Since all monitor framerates tend to be multiples of 5 (25, 30, 60, 75, and 120), this likely will improve accuracy. Setting precision to 1 disables this.

`renpy.` `get_renderer_info`()

  Returns a dictionary, giving information about the renderer Ren'Py is currently using. The dictionary has one required key:

  `"renderer"`
    One of `"gl"` or `"sw"`, corresponding to the OpenGL and software renderers, respectively.
  `"resizable"`
    True if and only if the window is resizable.
  `"additive"`
    True if and only if the renderer supports additive blending.

  Other, renderer-specific, keys may also exist. The dictionary should be treated as immutable. This should only be called once the display has been started (that is, after the init phase has finished).

`renpy.` `get_say_attributes`()

  Gets the attributes associated with the current say statement, or None if no attributes are associated with this statement.

  This is only valid when executing or predicting a say statement.

`renpy.` `get_side_image`(prefix_tag, image_tag=None, not_showing=True, layer='master')

  This attempts to find an image to show as the side image.

  It begins by determining a set of image attributes. If image_tag is given, it gets the image attributes from the tag. Otherwise, it gets them from the currently showing character.

  It then looks up an image with the tag prefix_tag and those attributes, and returns it if it exists.

  If not_showing is True, this only returns a side image if the image the attributes are taken from is not on the screen.

  If layer is None, uses the default layer for the currently showing tag.

`renpy.` `get_skipping`()

  Returns true if the Ren'Py is skipping, "fast" if Ren'Py is fast skipping, and false if it is not skipping.

`renpy.` `get_transition`(layer=None)

  Gets the transition for layer, or the entire scene if layer is None. This returns the transition that is queued up to run during the next interaction, or None if no such transition exists.

`renpy.` `iconify`()

  Iconifies the game.

`renpy.` `invoke_in_thread`(fn, *args, **kwargs)

  Invokes the function fn in a background thread, passing it the provided arguments and keyword arguments. Restarts the interaction once the thread returns.

  This function creates a daemon thread, which will be automatically stopped when Ren'Py is shutting down.

`renpy.` `is_seen`(ever=True)

  Returns true if the current line has been seen by the player.

  If ever is true, we check to see if the line has ever been seen by the player. If false, we check if the line has been seen in the current play-through.

`renpy.` `is_start_interact`()

  Returns true if restart_interaction has not been called during the current interaction. This can be used to determine if the interaction is just being started, or has been restarted.

`renpy.` `load_module`(name, **kwargs)

  This loads the Ren'Py module named name. A Ren'Py module consists of Ren'Py script that is loaded into the usual (store) namespace, contained in a file named name.rpym or name.rpymc. If a .rpym file exists, and is newer than the corresponding .rpymc file, it is loaded and a new .rpymc file is created.

  All of the init blocks (and other init-phase code) in the module are run before this function returns. An error is raised if the module name cannot be found, or is ambiguous.

  Module loading may only occur from inside an init block.

`renpy.` `load_string`(s, filename='<string>')

  Loads s as Ren'Py script that can be called.

  Returns the name of the first statement in s.

  filename is the name of the filename that statements in the string will appear to be from.

`renpy.` `maximum_framerate`(t)

  Forces Ren'Py to draw the screen at the maximum framerate for t seconds. If t is None, cancels the maximum framerate request.

`renpy.` `munge`(name, filename=None)

  Munges name, which must begin with __.

  filename
    The filename the name is munged into. If None, the name is munged into the filename containing the call to this function.

`renpy.` `not_infinite_loop`(delay)

  Resets the infinite loop detection timer to delay seconds.

`renpy.` `notify`(message)

  Causes Ren'Py to display the message using the notify screen. By default, this will cause the message to be dissolved in, displayed for two seconds, and dissolved out again.

  This is useful for actions that otherwise wouldn't produce feedback, like screenshots or quicksaves.

  Only one notification is displayed at a time. If a second notification is displayed, the first notification is replaced.

`renpy.` `pause`(delay=None, music=None, with_none=None, hard=False, checkpoint=None)

  Causes Ren'Py to pause. Returns true if the user clicked to end the pause, or false if the pause timed out or was skipped.

  delay
    If given, the number of seconds Ren'Py should pause for.
  music
    Retained for compatibility purposes.
  with_none
    Determines if a with None clause is executed at the end of the pause.
  hard
    If true, a click will not interrupt the pause. Use this sparingly, as it's hard to distinguish a hard pause from a crashing game.
  checkpoint
    If true, a checkpoint will be set, and players will be able to roll back to this statement. If false, no checkpoint will be set. If None, a checkpoint will only be set if delay is set.

`renpy.` `pop_call`()

  Pops the current call from the call stack, without returning to the location.

  This can be used if a label that is called decides not to return to its caller.

`renpy.` `queue_event`(name, up=False, **kwargs)

  Queues an event with the given name. Name should be one of the event names in `config.keymap`, or a list of such names.

  up
    This should be false when the event begins (for example, when a keyboard button is pressed.) It should be true when the event ends (when the button is released.)

  The event is queued at the time this function is called. This function will not work to replace an event with another - doing so will change event order. (Use `config.keymap` instead.)

  This method is threadsafe.

`renpy.` `quit`(relaunch=False, status=0)

  This causes Ren'Py to exit entirely.

  relaunch
    If true, Ren'Py will run a second copy of itself before quitting.
  status
    The status code Ren'Py will return to the operating system. Generally, 0 is success, and positive integers are failure.

`renpy.` `quit_event`()

  Triggers a quit event, as if the player clicked the quit button in the window chrome.

`renpy.` `reload_script`()

  Causes Ren'Py to save the game, reload the script, and then load the save.

`renpy.` `reset_physical_size`()

  Attempts to set the size of the physical window to the specified values in renpy.config. (That is, screen_width and screen_height.) This has the side effect of taking the screen out of fullscreen mode.

`renpy.` `restart_interaction`()

  Restarts the current interaction. Among other things, this displays images added to the scene, re-evaluates screens, and starts any queued transitions.

  This only does anything when called from within an interaction (for example, from an action). Outside an interaction, this function has no effect.

`renpy.` `screenshot`(filename)

  Saves a screenshot in filename.

`renpy.` `scry`()

  Returns the scry object for the current statement.

  The scry object tells Ren'Py about things that must be true in the future of the current statement. Right now, the scry object has one field:

  `nvl_clear`
    Is true if an `nvl clear` statement will execute before the next interaction.

`renpy.` `set_autoreload`(autoreload)

  Sets the autoreload flag, which determines if the game will be automatically reloaded after file changes. Autoreload will not be fully enabled until the game is reloaded with `renpy.utter_restart()`.

`renpy.` `set_mouse_pos`(x, y, duration=0)

  Jump the mouse pointer to the location given by arguments x and y. If the device does not have a mouse pointer, this does nothing.

  duration
    The time it will take to perform the move, in seconds. During this time, the mouse may be unresponsive.

`renpy.` `set_physical_size`(size)

  Attempts to set the size of the physical window to size. This has the side effect of taking the screen out of fullscreen mode.

`renpy.` `shown_window`()

  Call this to indicate that the window has been shown. This interacts with the "window show" statement, which shows an empty window whenever this functions has not been called during an interaction.

`renpy.` `split_properties`(properties, *prefixes)

  Splits up properties into multiple dictionaries, one per prefix. This function checks each key in properties against each prefix, in turn. When a prefix matches, the prefix is stripped from the key, and the resulting key is mapped to the value in the corresponding dictionary.

  If no prefix matches, an exception is thrown. (The empty string, "", can be used as the last prefix to create a catch-all dictionary.)

  For example, this splits properties beginning with text from those that do not:

      text_properties, button_properties = renpy.split_properties("text_", "")

`renpy.` `substitute`(s, scope=None, translate=True)

  Applies translation and new-style formatting to the string s.

  scope
    If not None, a scope which is used in formatting, in addition to the default store.
  translate
    Determines if translation occurs.

  Returns the translated and formatted string.

`renpy.` `transition`(trans, layer=None, always=False)

  Sets the transition that will be used during the next interaction.

  layer
    The layer the transition applies to. If None, the transition applies to the entire scene.
  always
    If false, this respects the transition preference. If true, the transition is always run.

`renpy.` `vibrate`(duration)

  Causes the device to vibrate for duration seconds. Currently, this is only supported on Android.

`layout.` `yesno_screen`(message, yes=None, no=None)

  This causes the a yes/no prompt screen with the given message to be displayed. The screen will be hidden when the user hits yes or no.

  message
    The message that will be displayed.
  yes
    An action that is run when the user chooses yes.
  no
    An action that is run when the user chooses no.

## Ren'Py Version

`renpy.` `version`(tuple=False)

  If tuple is false, returns a string containing "Ren'Py ", followed by the current version of Ren'Py.

  If tuple is true, returns a tuple giving each component of the version as an integer.

`renpy.version_string`

  The version number of Ren'Py, as a string of the form "Ren'Py 1.2.3.456".

`renpy.version_only`

  The version number of Ren'Py, without the Ren'Py prefix. A string of the form "1.2.3.456".

`renpy.version_tuple`

  The version number of Ren'Py, as a tuple of the form (1, 2, 3, 456).

`renpy.version_name`

  A human readable version name, of the form "Example Version."

`renpy.license`

  A string giving license text that should be included in a game's about screen.

## Memory Profiling

`renpy.` `diff_memory`(update=True)

  Profiles objects, surface, and texture memory use by Ren'Py and the game. Writes (to memory.txt and stdout) the difference in memory usage from the last time this function was called with update true.

  The accounting is by names in the store and in the Ren'Py implementation that the memory is reachable from. If an object is reachable from more than one name, it's assigned to the name it's most directly reachable from.

  As it has to scan all memory used by Ren'Py, this function may take a long time to complete.

`renpy.` `profile_memory`(fraction=1.0, minimum=0)

  Profiles object, surface, and texture memory use by Ren'Py and the game. Writes an accounting of memory use by to the memory.txt file and stdout.

  The accounting is by names in the store and in the Ren'Py implementation that the memory is reachable from. If an object is reachable from more than one name, it's assigned to the name it's most directly reachable from.

  fraction
    The fraction of the total memory usage to show. 1.0 will show all memory usage, .9 will show the top 90%.
  minimum
    If a name is accounted less than minimum bytes of memory, it will not be printed.

  As it has to scan all memory used by Ren'Py, this function may take a long time to complete.

`renpy.` `profile_rollback`()

  Profiles memory used by the rollback system. Writes (to memory.txt and stdout) the memory used by the rollback system. This tries to account for rollback memory used by various store variables, as well as by internal aspects of the rollback system.

## Contexts

`renpy.` `context`()

  Returns an object that is unique to the current context. The object is copied when entering a new context, but changes to the copy do not change the original.

  The object is saved and participates in rollback.

`renpy.` `context_nesting_level`()

  Returns the nesting level of the current context. This is 0 for the outermost context (the context that is saved, loaded, and rolled-back), and is non-zero in other contexts, such as menu and replay contexts.

## renpy.random

This object is a random number generator that implements the Python random number generation interface. Randomness can be generated by calling the various methods this object exposes. See the Python documentation for the full list, but the most useful are:

- `renpy.random.random()`

Return the next random floating point number in the range (0.0, 1.0).

- `renpy.random.randint(a, b)`

Return a random integer such that a <= N <= b.

- `renpy.random.choice(seq)`

Return a random element from the non-empty sequence seq.

Unlike the standard Python random number generator, this object cooperates with rollback, generating the same numbers regardless of how many times we rollback. It should be used instead of the standard Python random module.

    # return a random float between 0 and 1
    $ randfloat = renpy.random.random()

    # return a random integer between 1 and 20
    $ d20roll = renpy.random.randint(1, 20)

    # return a random element from a list
    $ randfruit = renpy.random.choice(['apple', 'orange', 'plum'])

- `renpy.random.Random(seed=None)`

Returns a new random number generator object separate from the main one, seeded with the specified value if provided.