Transform Statement

Thetransform statement creates a new transform. The syntax is:

atl_transform ::=  "transform"qualname ( "("parameters ")" )? ":"atl_block

The transform statement is run atinit time. The transformmay take a list of parameters, which works much the same way as a Pythonfunction definition, except that several kinds of parameters are currentlyforbidden, though they may be allowed in the future:

1. Positional-only parameters

2. Keyword-only parameters without a default value

3. Variadic positional parameters (*args)

4. Variadic keyword parameters (**kwargs)

The created object cannot be used as a transform until and unless all itsparameters have been given a value.

See also :ATL curry and partial parameter passing

qualname, the name of the transform, must be a set of dot-separated Pythonidentifiers. The transform created by the ATL block will be bound to that name,within the providedstore if one was provided.

transformleft_to_right:xalign0.linear2xalign1.repeattransformariana.left:xalign.3transformanimated_ariana_disp:"ariana"pause1."ariana_reverse"pause1.repeat

The created object is both a transform and a displayable, but as opposed to theimage statement, it is created as a variable (or a constant), rather than inthe namespace ofimages.

Image Statement with ATL Block

The second way to include ATL code in a script is as part of animagestatement. As its inline counterpart, it binds an image name(which may contain spaces) to the given transform. As there is no way to supplywith parameters, it's only useful if the transform defines an animation. Thesyntax is:

atl_image ::=  "image"image_name ":"atl_block

imageanimated_ariana_img:"ariana"pause1."ariana_reverse"pause1.repeat

Scene and Show Statements with ATL Block

The final way to use ATL is as part of ashow or scenestatement. This wraps the image that's being shown inside an ATL transformationwhich is created on the fly and applied to the image. The syntax is:

atl_show ::=stmt_show ":"atl_blockatl_scene ::=stmt_scene ":"atl_block

showeileenhappy:xalign1.scenebgwashington:zoom2.

Inline Contains Statement

The inline contains statement takes a single expression evaluating to adisplayable.

atl_contains ::=  "contains"simple_expression

This statement sets (or replaces) the child of the current ATL transform to thevalue of the expression, making it useful for animation.

transforman_animation:"1.png"pause2"2.png"pause2repeatimagemove_an_animation:containsan_animation# If we didn't use contains, we'd still be looping# and would never reach here.xalign0.0linear1.0yalign1.0

TheDisplayable Statement is less explicit and bears ambiguity withthe transform expression statement, but it allows for atransition to be used for replacing the child. Thisstatement can be particularly useful when an ATL transform wishes to contain,rather than include, a second ATL transform.

Number Statement

The number statement consists of a simple expression evaluating to an integer orfloating-point number. It can optionally be preceded by the keyword "pause".

atl_number ::=  "pause"?simple_expression

It is used as a number of seconds to pause execution for.

imageatlexample:# Displays logo_base.pngcontains"logo_base.png"# Pause for 1.0 seconds.pause1.0# Show logo_bw.png, with a dissolve."logo_bw.png"withDissolve(0.5,alpha=True)# Pause for 3 seconds3repeat

Properties Statement

This statement sets one or more transform properties to a new value.

atl_properties ::=atl_property+

atl_property ::=transform_propertysimple_expression

The statement first gives a series (at least one) of property names, eachfollowed by the new value to set it to. SeeList of Transform Properties for alist of transform properties, their meaning and the values they take.

transformrightoid:xalign.9transformariana.left:xanchor.3xpos100

Interpolation Statement

The interpolation statement is the main way of getting smoothly animatedtransformations.

atl_interp ::=  ((warpersimple_expression) | ("warp"simple_expressionsimple_expression)) (atl_interp_target+ | (":"atl_interp_target+ ))

atl_interp_target ::=  (atl_property+ ("knot"simple_expression)* )                       |atl_transform_expression                       | "clockwise"                       | "counterclockwise"                       | ("circles"simple_expression)

Some sample interpolations:

showlogobase:# Show the logo at the upper right side of the screen.xalign1.0yalign0.0# Take 1.0 seconds to move things back to the left.linear1.0xalign0.0# Take 1.0 seconds to move things to the location specified in the# truecenter transform. Use the ease warper to do this.ease1.0truecenter# Set the location to circle around.anchor(0.5,0.5)# Use circular motion to bring us to spiral out to the top of# the screen. Take 2 seconds to do so.linear2.0yalign0.0clockwisecircles3# Use a spline motion to move us around the screen.linear2.0align(0.5,1.0)knot(0.0,.33)knot(1.0,.66)# Changes xalign and yalign at the same time.linear2.0xalign1.0yalign1.0# The same thing, using a block.linear2.0:xalign1.0yalign1.0

The first part of the interpolation is used to select a function that time-warpsthe interpolation. That means, a function that maps linear time to non-lineartime, seeWarpers for more information about that. Selecting a warper caneither be done by giving the name of a registered warper, or by giving thekeyword "warp" followed by an expression giving a warping function.

In either case, it's followed by a number giving the number of seconds the interpolation should take.

transformbuiltin_warper:xpos0ease5xpos520initpython:defmy_warper(t):returnt**4.4definemy_warpers=[my_warper]transformaccessed_as_function:xpos0warpmy_warpers[0]5xpos520warpmy_warper3xpos100

The interpolation will persist for the given amount of time, and at least oneframe.

WhenTransform Properties are given, the value each is given is the valueit will be set to at the end of the interpolation statement. This can be tweakedin several ways:

• If the value is followed by one or more knots, then spline motion is used. Thestarting point is the value of the property at the start of the interpolation,the end point is the given value, and the knots are used to control thespline. A quadratic curve is used for a single knot, Bezier is used when thereare two and Catmull-Rom is used for three or more knots. In the former twocases, the knot or knots are simply control nodes. For Catmull-Rom, the firstand last knot are control nodes (often outside the displayed path) and theother knots are points the path passes through.

• If the interpolation statement contains a "clockwise" or "counterclockwise"clause, circular motion is used. In that case, Ren'Py will compare the startand end locations (which are set bypos,align,angle andradius, ...) and figure out the polar coordinatecenter (which isaround). Ren'Py will then compute the number ofdegrees it will take to go from the start angle to the end angle, in thespecified direction of rotation. If the circles clause is given, Ren'Py willensure that the appropriate number of circles will be made.

• Otherwise, the value is linearly interpolated between the start and endlocations.

It is also possible to interpolate aTransform Expression Statement,which should in this case be an ATL transform containing only a singleproperties statement. The properties from the transform will be processed as ifthey were written directly in this interpolation.

A warper may be followed by a colon (:). In that case, it may be followed by oneor more lines, in an indented block, containing the clauses described above.This lets you break an interpolation of many different things up into severallines.

Pass Statement

atl_pass ::=  "pass"

Thepass statement is a simple statement that causes nothing to happen : ano-op. This can be used when there's a desire to separate statements, like whentwo sets of choice statements (see below) would otherwise be back-to-back. Itcan also be useful when the syntax requires a block to be created but you needit to be empty, for example to make one of the choice blocks not do anything.

Repeat Statement

Therepeat statement is a simple statement that causes the block containingit to resume execution from the beginning.

atl_repeat ::=  "repeat" (simple_expression)?

If the expression is present, then it is evaluated to give an integer number oftimes the block will execute. (So a block ending withrepeat2 will executeat most twice in total, andrepeat1 does not repeat.)

The repeat statement must be the last statement in a block:

showlogobase:xalign0.0linear1.0xalign1.0linear1.0xalign0.0repeat

Block Statement

Theblock statement simply contains a block of ATL statements.

atl_block_stmt ::=  "block" ":"atl_block

This can be used to group statements that will repeat:

showlogobase:alpha0.0xalign0.0yalign0.0linear1.0alpha1.0block:linear1.0xalign1.0linear1.0xalign0.0repeat

Parallel Statement

Theparallel statement defines a set of ATL blocks to execute in parallel.

atl_parallel ::=  ("parallel" ":"atl_block)+

Parallel statements are greedily grouped into a parallel set when more thanone parallel block appears consecutively in a block. The set of all parallelblocks are then executed simultaneously. The parallel statement terminates whenthe last block terminates.

The blocks within a set should be independent of each other, and manipulatedifferentTransform Properties. When two blocks change the same property,the result is undefined.

showlogobase:parallel:xalign0.0linear1.3xalign1.0linear1.3xalign0.0repeatparallel:yalign0.0linear1.6yalign1.0linear1.6yalign0.0repeat

Choice Statement

Thechoice statement defines one of a set ofpotential choices. Ren'Py will pick one of the choices in the set, andexecute the ATL block associated with it, and then continue execution afterthe last choice in the choice set.

atl_choice ::=  ("choice" (simple_expression)? ":"atl_block)+

Choice statements are greedily grouped into a choice set when more than onechoice statement appears consecutively in a block. If thesimple_expressionis supplied, it is a floating-point weight given to that block, otherwise 1.0is assumed.

imageeileenrandom:choice:"eileen happy"choice:"eileen vhappy"choice:"eileen concerned"pause1.0repeat

Thepass statement can be useful in order to break several sets of choiceblocks into several choice statements, or to make an empty choice block.

Animation Statement

Theanimation statement must be the first statement in an ATL block, andtells Ren'Py that the block uses the animation timebase.

atl_animation ::=  "animation"

As compared to the normal showing timebase, the animation timebase starts whenan image or screen with the same tag is shown. This is generally used to haveone image replaced by a second one at the same apparent time. For example:

imageeileenhappymoving:animation"eileen happy"xalign0.0linear5.0xalign1.0repeatimageeileenvhappymoving:animation"eileen vhappy"xalign0.0linear5.0xalign1.0repeatlabelstart:showeileenhappymovingpauseshoweileenvhappymovingpause

This example will cause Eileen to change expression when the first pausefinishes, but will not cause her position to change, as both animations sharethe same animation time, and hence will place her sprite in the same place.Without the animation statement, the position would reset when the playerclicks.

On Statement

Theon statement defines an event handler.

atl_on ::=  "on"name (","name)* ":"atl_block

on blocks are greedily grouped into a single statement. On statement canhandle a single event name, or a comma-separated list of event names.

This statement is used to handle events. When an event is handled, handling ofany other event ends and handing of the new event immediately starts. When anevent handler ends without another event occurring, thedefault event isproduced (unless thedefault event is already being handled).

Execution of the on statement will never naturally end. (But it can be endedby the time statement, or an enclosing event handler.)

See the event statement for a way to produce arbitrary events, and seeExternal events for a list of naturally-produced events.

showlogobase:onshow:alpha0.0linear.5alpha1.0onhide:linear.5alpha0.0transformpulse_button:onhover,idle:linear.25zoom1.25linear.25zoom1.0

Transform Expression Statement

This statement includes another ATL transform as part of the current ATL block.

atl_transform_expression ::=simple_expression

This only applies if the ATL transform hasnot been supplied a child (seethe top of the page for how to do that), otherwise it will be interpreted as aDisplayable Statement. The contents of the provided ATL transformare included at the location of this statement.

transformmove_right:linear1.0xalign1.0imageatlexample:# Display logo_base.png"logo_base.png"# Run the move_right transform.move_right

Displayable Statement

The displayable statement consists of a simple Python expression evaluating toadisplayable, optionally followed by a with clausecontaining a second simple expression.

atl_displayable ::=simple_expression ("with"simple_expression)?

It is used to set or replace the child of the transform when the statementexecutes.

If awith clause is present, the second expression is evaluated as atransition, and the transition is applied between the oldchild and the new child. Be careful in that not all transitions will work inthis situation, notablyDict Transitions andmove- andease- transitions.

imageatlexample:# Displays logo_base.png"logo_base.png"# Pause for 1.0 seconds.1.0# Show logo_bw.png, with a dissolve."logo_bw.png"withDissolve(0.5,alpha=True)

If the expression evaluates to an ATL transformwith a child, the executionof this ATL block will only continue after the includee's ATL code runs.

Contains Block Statement

The contains block, like itsinline counterpart, sets the child of thetransform but in a different way.

atl_counts ::=  "contains" ":"atl_block

One or more contains blocks will be greedily grouped together inside a singlecontains statement, wrapped inside aFixed(), and set as the child of thetransform.

Each block should define a displayable to use, otherwise an error will occur.The contains statement executes instantaneously, without waiting for thechildren to complete.

imagetestdouble:contains:"logo.png"xalign0.0linear1.0xalign1.0repeatcontains:"logo.png"xalign1.0linear1.0xalign0.0repeat

Function Statement

Thefunction statement allows ATL to use Python code.

atl_function ::=  "function"simple_expression

The functions have the same signature as those used withTransform():

• The first argument is a transform object.Transform Properties can beset as attributes on this object.

• The second argument is the shown timebase, the number of seconds since thefunction began executing.

• The third argument is the animation timebase, which is the number ofseconds something with the same tag has been on the screen.

• If the function returns a number, it will be called again after that number ofseconds has elapsed. (0 seconds means to call the function as soon aspossible.) If the function returns None, control will pass to the next ATLstatement.

This function should not have side effects other than changing the transformobject in the first argument, and may be called at any time with any value aspart of prediction.

Note thatfunction is not a transform property, and that it doesn't have theexact same behavior asTransform()'sfunction parameter.

initpython:defslide_vibrate(trans,st,at,/):ifst>1.0:trans.xalign=1.0trans.yoffset=0returnNoneelse:trans.xalign=sttrans.yoffset=random.randrange(-10,11)return0labelstart:showlogobase:functionslide_vibratepause1.0repeat

Time Statement

Thetime statement is a control statement.

atl_time ::=  "time"simple_expression

It contains a single expression, which is evaluated to give a time expressed asseconds from the start of execution of the containing block. When the time givenin the statement is reached, the following statement begins to execute. Thistransfer of control occurs even if a previous statement is still executing, andcauses any such prior statement to immediately terminate.

Time statements are implicitly preceded by a pause statement with an infinitetime. This means that if control would otherwise reach the time statement, itwaits until the time statement would take control.

When there are multiple time statements in a block, they must strictlyincrease in order.

imagebackgrounds:"bg band"xoffset0block:linear1xoffset10linear1xoffset0repeat# control would never exit this blocktime2.0xoffset0"bg whitehouse"time4.0"bg washington"

Event Statement

Theevent statement is a simple statement that causes an event with thegiven name to be produced.

atl_event ::=  "event"name

When an event is produced inside a block, the block is checked to see if anevent handler for the given name exists. If it does, control is transferredto the event handler. Otherwise, the event propagates to any containing eventhandler.