.. Automatically generated file - do not modify.

.. function:: 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

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: renpy.clear_game_runtime()
    
    Resets the game runtime counter.

.. function:: renpy.clear_keymap_cache()
    
    Clears the keymap cache. This allows changes to :var:`config.keymap` to
    take effect without restarting Ren'Py.

.. function:: 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")

.. function:: renpy.count_dialogue_blocks()
    
    Returns the number of dialogue blocks in the game's original language.

.. function:: renpy.count_newly_seen_dialogue_blocks()
    
    Returns the number of dialogue blocks the user has seen for the first time
    during this session.

.. function:: renpy.count_seen_dialogue_blocks()
    
    Returns the number of dialogue blocks the user has seen in any play-through
    of the current game.

.. function:: 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")

.. function:: 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.

.. function:: 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.

.. function:: renpy.force_full_redraw()
    
    Forces the screen to be redrawn in full. Call this after using pygame
    to redraw the screen directly.

.. function:: renpy.free_memory()
    
    Attempts to free some memory. Useful before running a renpygame-based
    minigame.

.. function:: 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 :var:`config.end_game_transition`.

.. function:: renpy.get_adjustment(bar_value)
    
    Given `bar_value`, a  :class:`BarValue`, returns the :func:`ui.adjustment`
    if uses. The adjustment has the following to attributes defined:
    
    .. attribute:: value
    
        The current value of the bar.
    
    .. attribute:: range
    
        The current range of the bar.

.. function:: renpy.get_autoreload()
    
    Gets the autoreload flag.

.. function:: 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.)

.. function:: 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.

.. function:: 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.

.. function:: renpy.get_physical_size()
    
    Returns the size of the physical window.

.. function:: 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.

.. function:: 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).

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: renpy.iconify()
    
    Iconifies the game.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: renpy.not_infinite_loop(delay)
    
    Resets the infinite loop detection timer to `delay` seconds.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: renpy.queue_event(name, up=False, **kwargs)
    
    Queues an event with the given name. `Name` should be one of the event
    names in :var:`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 :var:`config.keymap` instead.)
    
    This method is threadsafe.

.. function:: 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.

.. function:: renpy.quit_event()
    
    Triggers a quit event, as if the player clicked the quit button in the
    window chrome.

.. function:: renpy.reload_script()
    
    Causes Ren'Py to save the game, reload the script, and then load the
    save.

.. function:: 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.

.. function:: 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.

.. function:: renpy.screenshot(filename)
    
    Saves a screenshot in `filename`.
    
    Returns True if the screenshot was saved successfully, False if saving
    failed for some reason.

.. function:: 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.

.. function:: 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 :func:`renpy.utter_restart`.

.. function:: 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.

.. function:: 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.

.. function:: 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.

.. function:: 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_", "")

.. function:: 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.

.. function:: 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.

.. function:: renpy.vibrate(duration)
    
    Causes the device to vibrate for `duration` seconds. Currently, this
    is only supported on Android.

.. function:: 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.

