=============================
Other Functions and Variables
=============================

This page lists and documents various miscellaneous functions and variables
not better listed somewhere else.


Ren'Py Version
--------------

.. include:: inc/renpy_version

.. var:: renpy.version_string

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

.. var:: renpy.version_only

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

.. var:: renpy.version_tuple

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

    This is a namedtuple with four fields: ``major``, ``minor``, ``patch``,
    and ``commit``.

.. var:: renpy.version_name

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

.. var:: renpy.license

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

Platform Detection
-------------------

Ren'Py includes a number of variables that are set based on which platform
it's running on.

.. var:: renpy.windows

    Has a true value when running on Windows.

.. var:: renpy.macintosh

    Has a true value when running on macOS.

.. var:: renpy.linux

    Has a true value when running on Linux or other POSIX-like operating systems.

.. var:: renpy.android

    Has a true value when running on Android.

.. var:: renpy.ios

    Has a true value when running on iOS.

.. var:: renpy.emscripten

    Has a true value when running in the browser. That value is specifically the
    emscripten module that lets you interact with the browser, see :func:`renpy.emscripten.run_script`
    and similar functions.

.. var:: renpy.mobile

    Has a true value when running on Android or iOS or in the browser.

These are only set when running on the actual devices, not when running on
in the emulators. These are more intended for use in platform-specific
Python. For display layout, use :ref:`screen variants <screen-variants>`.


Memory Profiling
-----------------

.. include:: inc/memory

renpy.random
-------------

This object is a random number generator that implements
`the Python random number generation interface <https://docs.python.org/library/random.html>`_.
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`.

* ``renpy.random.shuffle(seq)``

Shuffles the elements of the sequence `seq` in place. This does not return
a list, but changes an existing one.

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.

.. _SDL:

SDL
----

The SDL2 dll can be accessed using :func:`renpy.get_sdl_dll`.
This allows the use of SDL2 functions directly. However, using them often
requires knowledge of the Python ctypes module.

There are no guarantees as to the version of SDL2 that's included
with Ren'Py, including which features will or will not be compiled in. These
functions may fail on platforms that can otherwise run Ren'Py. It's
important to check for a None value before proceeding.

In the following example, the position of the window will be taken from SDL2::

    init python:

        import ctypes

        def get_window_position():
            """Retrieves the position of the window from SDL2.

            Returns the (x, y) of the upper left corner of the window, or
            (0, 0) if it's not known.
            """

            sdl = renpy.get_sdl_dll()

            if sdl is None:
                return (0, 0)

            win = renpy.get_sdl_window_pointer()

            if win is None:
                return (0, 0)

            x = ctypes.c_int()
            y = ctypes.c_int()

            result = sdl.SDL_GetWindowPosition(win, ctypes.byref(x), ctypes.byref(y))

            return result


.. include:: inc/sdl

Miscellaneous
-------------

.. include:: inc/other
