This section has been made somewhat obsolete by the introduction of ATL in Ren'Py 6.10.
The result of these functions are suitable for use as the argument to the "at" clause of the scene and show statements. The result can also be called (using a second call) to return a displayable.
Function: Position(**properties):
Position, when given position properties as arguments, returns a callable that can be passed to the "at" clause of a show or scene statement to display the image at the given location. See the Position Properties section to get a full explanation of how they are used to lay things out.
118
Function: Motion(function, period, repeat=False, bounce=False, time_warp=None,
add_sizes=False, anim_timebase=False, **properties):
Motion, when given the appropriate arguments, returns an object that when given as the `at` clause of an image causes an image to be moved on the screen.
function is a function that takes one or two arguments. The first argument is a fraction of the period, a number between 0 and 1. If add_sizes is true, function should take a second argument, a 4-tuple giving the width and height of the area in which the child will be shown, and the width and height of the child itself.
function should return a tuple containing two or four values. The first two values are interpreted as the xpos and the ypos of the motion. (Please note that if these values are floating point numbers, they are interpreted as a fraction of the screen. If they are integers, they are interpreted as the absolute position of the anchor of the motion.) If four values are returned, the third and fourth values are interpreted as an xanchor and yanchor.
Please note that the function may be pickled, which means that it cannot be an inner function or a lambda, but must be a function defined in an init block of your script. In general, it's better to use a Pan or a Move, rather than defining your own motion.
period is the time, in seconds, it takes to complete one cycle of a motion. If repeat is True, then the cycle repeats when it finishes, if False, the motion stops after one period. If bounce is True, the argument to the function goes from 0 to 1 to 0 in a single period, if False, it goes from 0 to 1.
time_warp, if given, is a function that takes a fractional time period (a number between 0.0 and 1.0) and returns a fractional time period. This allows non- linear motions. This function may also be pickled.
anim_timebase is true to use the animation timebase, false to use the displayable timebase.
119
Function: Pan(startpos, endpos, time, repeat=False, bounce=False, time_warp=None,
**properties):
Pan, when given the appropriate arguments, gives an object that can be passed to the at clause of an image to cause the image to be panned on the screen. The parameters startpos and endpos are tuples, containing the x and y coordinates of the upper-left hand corner of the screen relative to the image. time is the time it will take this position to move from startpos to endpos. repeat, bounce, and time_warp are as for Motion.
As the current implementation of Ren'Py is quite limited, there are quite a few restrictions that we put on pan. The big one is that there always must be a screen's worth of pixels to the right and below the start and end positions. Failure to ensure this may lead to inconsistent rendering.
Please note that the pan will be immediately displayed, and that Ren'Py will not wait for it to complete before moving on to the next statement. This may lead to the pan being overlayed with text or dialogue. You may want to use a call to renpy.pause to delay for the time it will take to complete the pan. Finally, also note that when a pan is completed, the image locks into the ending position.
Function: Move(startpos, endpos, time, repeat=False, bounce=False, time_warp=None,
**properties):
Move is similar to Pan, insofar as it involves moving things. But where Pan
moves the screen through an image, Move moves an image on the screen. Specifially, move changes the position style of an image with time.
Move takes as parameters a starting position, an ending position, the amount of time it takes to move from the starting position to the ending position, and extra position properties. The postions may either be pairs giving the xpos and ypos properties, or 4-tuples giving xpos, ypos, xanchor, and yanchor. These properties may be given as integers or floating point numbers, but for any property it's not permissible to mix the two. repeat, bounce, and time_warp are as for Motion.
In general, one wants to use Pan when an image is bigger than the screen, and
120
Function: SplineMotion(points, time, anchors=(0.5, 0.5), repeat=False, bounce=False,
anim_timebase=False, time_warp=None, **properties):
This creates a spline-based motion, where a spline may consist of linear segments, quadratic beziers, and cubic beziers.
The path is a list of segments, where each segment is a tuple containing between 1 to 3 points, and an optional time. A point is represented by either an (x, y) pair or an (x, y, xanchor, yanchor) tuple. When not specified in a point, the anchors are taken from the anchors parameter. The time is
represented as a floating point number between 0.0 and 1.0, and gives the time when motion along the segment should be complete.
A linear segment consists of a single point, the point to move to.
A quadratic curve contains two points, the point to move to and the single control point.
A cubic curve contains three points, the point to move to and the two control points.
Any time you don't manually specify is linearly interpolated between the previous and following times that are specified. This allows you to specify that at a specific time, the motion will be at a specific point. By default, the start time is 0.0 and the end time is 1.0, unless you specify something different.
There is a spline editor that helps with editing splines.
Repeat, bounce, anim_timebase, and time_warp are as for Motion.
anim.SMAnimation can also be used to declare complicated motions. Use None instead of an image in States, and supply a move transition when moving between states. A SMAnimation so created can be passed in to the at clause of an image, allowing it to move things around the screen.
These movement clauses can also be used as Transitions, in which case they affect the position of a single layer or the entire screen, as appropriate.
121
Function: Zoom(size, start, end, time, after_child=None, time_warp=None,
bilinear=True, opaque=True, anim_timebase=False, repeat=False, **properties):
This causes a zoom to take place, using image scaling. When used as an `at` clause, this creates a displayable. The render of this displayable is always of the supplied size. The child displayable is rendered, and a rectangle is cropped out of it. This rectangle is interpolated between the start and end rectangles. The rectangle is then scaled to the supplied size. The zoom will take time seconds, after which it will show the end rectangle, unless an after_child is given.
The start and end rectangles must fit completely inside the size of the child, otherwise an error will occur.
size - The size that the rectangle is scaled to, a (width, height) tuple. start - The start rectangle, an (xoffset, yoffset, width, height) tuple. end - The end rectangle, an (xoffset, yoffset, width, height) tuple.
time - The amount of time it will take to interpolate from the start to the end rectangle.
after_child - If present, a second child widget. This displayable will be rendered after the zoom completes. Use this to snap to a sharp displayable after the zoom is done.
time_warp - If not None, a function that takes a fractional period (between 0.0 and 0.1), and returns a fractional period. Use this to implement non-linear zooms. This function may be pickled, so it cannot be a lambda or other non- top-level function.
bilinear - If True, the default, this will use bilinear filtering. If false, this will use ugly yet fast nearest neighbor filtering.
opaque - If True and bilinear is True, this will use a very efficient method that does not support transparency. If False, this supports transparency, but is less efficient.
anim_timebase - is true to use the animation timebase, false to use the displayable timebase.
122
Function: FactorZoom(start, end, time, after_child=None, time_warp=None,
bilinear=True, opaque=True, anim_timebase=False, repeat=False, **properties):
This causes a zoom to take place, using image scaling. When used as an `at` clause, this creates a displayable. The render of this displayable is always of the supplied size. The child displayable is rendered, and then scaled by an appropriate factor, interpolated between the start and end factors. The
rectangle is then scaled to the supplied size. The zoom will take time seconds, after which it will show the end, unless an after_child is given.
The algorithm used for scaling does not perform any interpolation or other smoothing.
start - The start zoom factor, a floating point number. end - The end zoom factor, a floating point number.
time - The amount of time it will take to interpolate from the start to the end factors.
after_child - If present, a second child widget. This displayable will be rendered after the zoom completes. Use this to snap to a sharp displayable after the zoom is done.
time_warp - If not None, a function that takes a fractional period (between 0.0 and 0.1), and returns a fractional period. Use this to implement non-linear zooms. This function may be pickled, so it cannot be a lambda or other non- top-level function.
bilinear - If True, the default, this will use bilinear filtering. If false, this will use ugly yet fast nearest neighbor filtering.
opaque - If True and bilinear is True, this will use a very efficient method that does not support transparency. If False, this supports transparency, but is less efficient.
anim_timebase - is true to use the animation timebase, false to use the displayable timebase.
123
Function: RotoZoom(rot_start, rot_end, rot_delay, zoom_start, zoom_end,
zoom_delay, rot_repeat=False, zoom_repeat=False, rot_bounce=False, zoom_bounce=False,
rot_anim_timebase=False, zoom_anim_timebase=False, rot_time_warp=None, zoom_time_warp=None, opaque=False, **properties):
This function returns an object, suitable for use in an at cause, that rotates and/or zooms its child.
rot_start - The number of degrees of clockwise rotation at the start time. rot_end - The number of degrees of clockwise rotation at the end time. rot_delay - The time it takes to complete rotation.
zoom_start - The zoom factor at the start time. zoom_end - The zoom factor at the end time.
zoom_delay - The time it takes to complete a zoom.
rot_repeat - If true, the rotation cycle repeats once it is finished. zoom_repeat - If true, the zoom cycle repeats once it is finished.
rot_bounce - If true, rotate from start to end to start each cycle. If False, rotate from start to end once.
zoom_bounce - If true, zoom from start to end to start each cycle. If False, zoom from start to end once.
rot_anim_timebase - If true, rotation times are judged from when a
displayable with the same tag was first shown. If false, times are judged from when this displayable was first shown.
zoom_anim_timebase - If true, zoom times are judged from when a
displayable with the same tag was first shown. If false, times are judged from when this displayable was first shown.
opaque - This should be True if the child is fully opaque, and False otherwise. RotoZoom uses a bilinear interpolation method that is accurate when the zoom factor is >= 0.5.