Placement#

This is a brief overview with examples of placing stuff in Ren’Py. It’s useful for beginners and as a refresher for more advanced game developers. For a quick reference, see Position Cheat Sheet.

Placing#

Great introduction to positioning images already exists in the official Ren’Py documentation on Transforms, so we’ll focus here on working with screens.

Three most important and widely used positioning properties in Ren’Py are pos (position), anchor and align.

pos, anchor, align (and many other position properties) have 3 variants:

  • by x,

  • by y

  • and both:

Variant

Effect

xpos

positions by x (from left)

ypos

positions by y (from top)

pos

positions by both x and y

xanchor

sets anchor by x

yanchor

sets anchor by y

anchor

sets anchor by both x and y

xalign

aligns by x

yalign

aligns by y

align

aligns by both x and y

pos sets the position of its element (a.k.a. displayable) in the containig area. (Which can be the whole display or a container element, such as frame, fixed etc.)


anchor of a displayable sets by which point it’s “anchored” to its position. I.e., if anchor is in the center of the displayable, then it’s the center that’s positioned at given coordinates. If anchor is in the top-left corner, then it’s the top-left corner that’s positioned at the given coordinates. Here’s an image with pos (0.6, 0.5). See how it moves when we vary its anchor:


align is giving a displayable the same value for anchor and position. It’s a fast and simple way to place a displayable in a containing area, because it can, for example:

xalign 0.

align the left side of the displayable with the left edge of the area

xalign 1.

align the right side of the displayable with the right edge of the area

xalign .5

align the center of the displayable with the center of the area
_images/align.webp

The fourth most interesting position property is offset. It shifts the position of a displayable by an amount of pixels. It’s especially useful when you want to shift something beyond the borders of its parent element. (I also use offset when a displayable has some convoluted positioning and I don’t want to change it, only quickly modify it by a known number of pixels.)

_images/offset.webp

Note

pos and anchor can have all kinds of positioning parameters. But offset takes only integers (amount of pixels), and align takes only float parameters (as fractions). See the detailed explanation below.

Always keep in mind the difference between integer and float parameters. For example, if you position a displayable by a number of pixels, and that number receives a non-integer value, the displayable will likely disappear from the screen, because the float parameter will be interpreted as fraction of the containing area size (and the displayable might be placed far beyond the screen borders).

So when a number of px can get non-integer values, either round it to integer, e.g. with int(), or use absolute() (see below).

Position Cheat Sheet#

Full and regularly updated reference: official Ren’Py docs on Style Properties.

Most position properties can have any position as a parameter:

Type

Meaning

integer

The amount of pixels (x — from left, y — from top).

float number

The fraction

  • of the containing area (x — from left, y — from top).

  • For anchor, the fraction of the displayable size.

absolute(num)

absolute can be used for subpixel precision, treating a float number as the amount of pixels.

position (abs, rel)

Adds pixels and fraction into one position value, for example:

  • position(-50, 0.5) = 50 px less than at the center

  • position(30, .25) = at 25% + 30 px

Position properties#

Property

Parameter

Effect
align (x, y)
xalign x
yalign y
float
(fraction)

Align in the containing area, by setting pos and anchor to the same value.
anchor (x, y)
xanchor x
yanchor y

position

Set at which point the displayable is anchored to its position.
area
(xpos, ypos,
width, height)
int
(pixels)

Attempts to position the displayable such that it’s upper-left corner is at xpos and ypos, and its size is width and height. (Works not for every displayable and layout).
maximum (x, y)
xmaximum x
ymaximum y
int
(pixels)

Maximum size of the displayable.
minimum (x, y)
xminimum x
yminimum y
int
(pixels)

Minimum size of the displayable. (Only works with displayables that can vary their size).
offset (x, y)
xoffset x
yoffset y
int
(pixels)

Shifts the position of the displayable.
pos (x, y)
xpos x
ypos y

position

Sets the position of the displayable (x — from left side, y — from top).
xfill ?
yfill ?

bool
True => the displayable expands to fill all available space.
False => It’s only large enough to contain its children.
This only works for displayables that can change size.
xycenter (x, y)
xcenter x
ycenter y

position

Positions the displayable by its center (setting align to 0.5).
xysize (x, y)
xsize x
ysize y
int (px)
or float
(fraction)

Sets the size of the displayable (= set minimum and maximum to the same value).

Containers#

Most widely used container displayables are

  • frame: creates an area with background, to place child displayables there.

  • hbox: places items in a row automatically.

  • vbox: places items in a column automatically.

  • grid: places items in rows and columns.

  • viewport: creates a scrollable area.

Also to combine displayables we can use:

Note

  • Using containers, take into account their padding parameter, as it adds to the pixel position of child displyables in that container.

  • Positions of child displayables in hbox, vbox and grid are defined by padding and spacing of those, so trying to set children’s properties like pos would likely fail.