Revision as of 12:54, 7 April 2009

Introduction

The 'OneShotMod' avatar animations are examples of 'advanced' avatar animations that are triggered by a script. They are mostly used when the avatar interact with an object: touching a book, pushing a button, pulling a lever, and so on. They also can be used for other things, like entering the elevators in Garrison. Those animations are important for all interactions in an Age, and if they are used well they can enhance it a lot.

Those animations must be triggered through Alcscript. However those animations are 'fixed', which means that the avatar will always plays the exact same animation, regarless of where the interactive object is. For example: if you want the avatar to touch a book using the standard linking book animation but you create the book right on the ground, the avatar will 'miss' it. So, in order that those animations look right the objects must be made to fit the animations; they must have a certain size, be at a certain height... etc.

This list goes through some of the most common animations and the required objects, and tries to give all needed information to use them correctly.

Also on this page is a Blender scene containing a visual reference for all those animations.

Commonly Used Animations

NOTE: Remember that these animations are only for the avatar; if you want to animate some of the objects (levers, buttons, etc.) you will have to do it yourself. For small objects (buttons especially) it may look OK if they are not animated; but for larger objects, you definitely need to (which can be difficult if you want to properly synchronize it with the avatar animation).

Another important note: This list also mentions age specific animations (i.e. non-global), but these will not work unless you import them first. [See the Rotating Door animation below for details on how to do this.]

Callback Warning Some animations do not use their names as their markers for callbacks. The following list contains the correct list of markers where noted.

Linking book

This is the regular 'Touch the linking book panel' animation used for most books. Unfortunately, using this animation as a one-shot will result in your avatar getting stuck on the book, unless you trigger a link out via AlcScript. [As of April 2009, this is not currently supported.] To do this properly, you should use a PythonFileMod in conjunction with a fan-age version of the xLinkingBookGUIPopup (the URU version only allows you to link to URU ages). Plus, you'll need a MultistageBehMod to trigger the animation once the user has clicked the linking panel on the pop-up book. [As of April 2009, this is not currently supported.]

Dimensions:

Animation: "GlobalAnimations_District_*LinkOut"
Name: "LinkOut"
Callback Marker: "touch"
URU Example: spyroom_district_spyroom.prp

Door button

This is the regular button animation used for most doors (like the Relto hut door) but it is can also used for other things like for touching the Journey cloths, or any action that requires a large button on a wall.
The button must be around 3.6 units above the ground.
Animation: "GlobalAnimations_District_*DoorButtonTouch"
Name: "DoorButtonTouch"
Callback Marker: "DoorButtonTouch"

'Flat' button

This one is for the small buttons on pedestals found in many Uru Ages (the Hood light buttons on the bridge, the Teledahn elevator, the Gira lanterns in the caves, etc)
The button must be around 3.5 units above the ground.
Animation: "GlobalAnimations_District_*ButtonTouch"
Name: "ButtonTouch"
Callback Marker: "TouchButton"

Sitting regions

Use for all the chairs and benches, those don't actually require animations, they are used automatically like the ladders. They still require the object to be at exactly 2 unis above the ground, and at least 1.4 unit large.

Also if you want to have a table or a desk near it, make sure that it is at least 1 unit above the chair.
The eyes of a sitting male avatar are 4.55 units off the floor, 4.3 units for female avatars.

Wall lever

This is the regular 'small lever on the wall' used in the Relto hut for the window, in the teledahn office etc.. There are two animations depending whether the lever is on the 'up' or 'down' position.
For the 'down' position the lever handle must be around 3.8 units above the ground, for the 'Up' position it is around 4.3 The handle should switch positions in about 10 frames (1/3 second) after the callback.
Animation: "GlobalAnimations_*BlindsLeverUp"
Name: "BlindsLeverUp"
Callback Marker: "LeverUp"
Animation: "GlobalAnimations_*BlindsLeverDown"
Name: "BlindsLeverDown"
Callback Marker: "LeverDown"

Scopes

All scopes in Uru works pretty much the same way and they use several animations. First the avatar has to grab the scope by the handles, then it holds it as long as it uses it, and then finally it releases it.
Animation: "GlobalAnimations_ScopeGrab"
Animation: "GlobalAnimations_ScopeHold"
Animation: "GlobalAnimations_ScopeRelease"

Revolving doors

Most doors in Uru are sliding doors, however there is a regular non-sliding door, which is only used in the Teledahn warShroom. It requires some pretty specific dimensions (size of the door, size and position of the handle on the door etc). Also it causes various other issues, most notably in a multi-player environment you can slam the door in someone else's face. So it is not very easy to use; which is probably why it wasn't used much in Uru Ages.
For the full dimensions of this object look at the blender scene at the end of this article.
There are two animations depending on which side of the door the avatar is.
Animation: "Teledahn_NoxiousCaveDoorPullOpen"
Callback Marker: "DoorOpen"
Animation: "Teledahn_NoxiousCaveDoorPushOpen"
Callback Marker: "DoorOpen"

Relto Bahro Poles Book

This is a slight variant of the common Linking Book animation, here the avatar has to kneel to use touch the book. In Uru this is mostly used for the Relto Bahro poles books, and for most of the Bahro stones. This can be useful if you want to have a book near the ground. Book panel must be at 2 units above the ground.
Animation: "GlobalAnimations_FishBookLinkOut ???"
Callback Marker: "touch"

More animations

WARNING: The rest of this information has not been verified; use it at your own risk.

There are many other animations in Uru, some of which are listed here, and if you want to add more informations and move that to the main section of this document, please do it (this is a wiki after all ;) ). Also there are more animations for the objects listed previously, some of those can help you in your Age or give you ideas, so don't hesitate to have a look at the Uru/Dat folder for a list of all the animations (look for the files with 'Female' or 'Male' in their names).

Pedal
Used for the Cleft bucket, the Eder Gira vents, the Teledahn elevator brake etc.
Animation: "GlobalAnimations_StepOnFloorPlate"
Callback Marker: "PlateDown"

Floor lever
The big lever near the Teledahn bucket, or in the Kadish Pillars puzzle etc
Animation: "GlobalAnimations_FloorLeverA"
Callback Marker: "LeverBack"

Animation: "GlobalAnimations_FloorLeverAPullHard"
Callback Marker: "pull"

Animation: "GlobalAnimations_FloorLeverAPushHard"
Callback Marker: "pushvww"

Animation: "GlobalAnimations_FloorLeverAUp"
Callback Marker: "LeverUp233"

Big floor lever (aka Clutch lever)
This animation is only used in Teledahn for the 3 levers around 'solar panel' tower. The avatar uses both his arms to push the lever here.
Animation: "Teledahn_ClutchLeverForward"
Animation: "Teledahn_ClutchLeverBackward"

Wall wheel
Only used in Ahnonay inside the sphere1 tower, could be useful for mechanical puzzles.
Animation: "AhnySphere01_ValveWheelCW" (clockwise)
Callback Marker: "WheelCW"
Animation: "AhnySphere01_ValveWheelCCW" (counterclockwise)
Callback Marker: "WheelCCW"

Garrison Elevators
That's a pretty specific animation, but a big advantage of it is that with this system the elevator is fully automatic, no need for buttons inside or a complex GUI. Also you don't really see the inside of the elevator, Which could be useful if you can't spend too much time creating it. Finally small elevators are problematic for the third person camera; which isn't suited for such small spaces.
Animation: "Garrison_ElevatorArrivingBottom"
Animation: "Garrison_ElevatorArrivingTop"
Animation: "Garrison_ElevatorLeavingBottom"
Animation: "Garrison_ElevatorLeavingTop"

"Pump button"
The big yellow Teledahn power tower button that you have to push three times to start the solar panel.
Animation: "Teledahn_PowerTowerPrimerButton"

"Fall from the bucket"
That's in Teledahn when you get out of the bucket in the upper shroom. I'm not sure how it could be used, but it's a pretty unique animation, so it might as well be listed here. (a slightly similar animation is the Cleft_CleftDropIn)
Animation: "Teledahn_GetOutOfBucket"

UseKi
This is the 'put you hand in the machine' animation used for the Nexus stations and in the Great Zero. Because in MO:RE we'll be allowed to use D'ni material this animations may be useful for.
Animation: "GlobalAnimations_InsertKiHand"
Callback Marker: HandIn
Callback Marker: SndHandIn

Again there are many other animations in Uru, so feel free to add some here. A full list without descriptions can be found in the discussion for this article.

Blender File

For your convenience, a sample Blender file has been provided below. It contains objects annotated with the proper dimensions to fit the commonly used animations listed above, along with the appropriate AlcScript for the clickable objects and one shot modifiers.

• AvatarAnimations.blend (551kb) - Version 0.2 -- April 7 2009

In fact, this is a working age that you can export and test! Before you export it, be sure to configure your Blender sounds path so that it can locate the URU sound effects. (Click here to see how to do this.) After exporting, place the PAK file in the Python subdirectory of your URU installation. Then use ULM to add your age to your Relto book, and test it out.

• AvatarAnimations.pak

Alcscripts

In Alcscript the avatar animation must be referenced without any prefix. For example GlobalAnimations_District_FemaleDoorButtonTouch becomes DoorButtonTouch in your Alcscript, so that it can be applied to all genders (yes, Uru has more than two of them ;) ).

Seek Points

Avatar animations require a "seek point", this is the point where the avatar moves to before playing the actual animation. Those are not a fixed position, but you might want them to be in front of the object and at least two feet away from it. To create a seek point object simply add an "Empty".

Note: The local Y axis of the seek point (e.g. the green axis) must be pointed away from the object of interest. If you forget to orient this correctly, your avatar will perform the animation in the wrong direction.

Here is an example Alcscript for an avatar animation triggered by a clickable activator.

<clickable object>:
    logic:
        modifiers:
          - name: <modifier name>
            cursor: poised
            flags:
              - localelement
            activators:
              - type: objectinvolume
                remote: <click region>
                triggers:
                  - any
            conditions:
              - type: activator
                activators:
                  - type: picking
              - type: objectinbox
                satisfied: true
            actions:
              - type: responder
                ref: :<responder name>
        actions:
          - type: responder
            name: <responder name>
            responder:
                states:
                  - cmds:
                      - type: oneshotmsg
                        params:
                            receivers:
                              - oneshotmod:<seek point name>
                        waiton: -1
                    nextstate: 0
                    waittocmd: 0
                curstate: 0
                flags:
                  - detecttrigger

<seek point object>:
    logic:
        actions:
          - type: oneshot
            name: <seek point name>
            oneshot:
                animation: <avatar animation name>

Advanced oneshot parameters

• seektime: Default = 2.0. The number of seconds the avatar will attempt to walk towards the seek point. When the seektime times out the avatar warps to the seek point.

• drivable: Default = False. Unknown.

• reversable: Default = False. Another spelling error here. ;) Presumably to play an avatar animation backwards. Not tested.

• smartseek: Default = True. By default the avatar will try to walk towards the seek point. When set to False the avatar slides smoothly towards the seek point, ignoring colliders. When disabling smartseek it is recommended to set up your clickable with a small region and use the facing condition.

• noseek: Default = False. If you set this to True the avatar will not even attempt to move towards the seek point. It will do the animation where it stands. However, setting smartseek to True overrides this!

For the default oneshot behavior you can leave these out of your Alcscript.

Here is an example which disables smartseek. This can be useful for subworlds where smartseek may sometimes fail.

<seek point object>:
    logic:
        actions:
          - type: oneshot
            name: <seek point name>
            oneshot:
                animation: <avatar animation name>
                seektime: 2.0
                drivable: false
                reversable: false
                smartseek: false
                noseek: false

Callbacks: Waiting on the avatar

An avatar animation is not the main action for a clickable. Usually we are opening a door, playing a sound, activating a Python script etc. However, the main action should always wait until the avatar animation has finished. In order to make it so we can add a callback message.

A callback message needs two references: a marker and a receiver. The marker is a name defined within the avatar animation (a list of valid marker names for each global avatar animation will be provided soon). The receiver is the responder which started it (hence callback). When the animation finishes the responder receives the callback message and continues with the next command.

In order for a command to wait its waiton value must be set. By default the waiton value is -1 which means "do not wait". A value of 0 (or any other number > 0) means "wait". The waiton value must match the waittocmd key.

A command with the waiton value set will not be executed until the message it specifies has been received. This will block the execution of the following commands as well. The specified message is the waittocmd msg value which must match the user id of the callback message that should be received by the responder.

Confused? You won't be after the next example. The Alcscript here is basically the same as shown previously but this time with a callback added to play a sound after the avatar animation has finished.

<clickable object>:
    logic:
        modifiers:
          - name: <modifier name>
            cursor: poised
            flags:
              - localelement
            activators:
              - type: objectinvolume
                remote: <click region>
                triggers:
                  - any
            conditions:
              - type: activator
                activators:
                  - type: picking
              - type: objectinbox
                satisfied: true
            actions:
              - type: responder
                ref: :<responder name>
        actions:
          - type: responder
            name: <responder name>
            responder:
                states:
                  - cmds:
                      - type: oneshotmsg
                        params:
                            receivers:
                              - oneshotmod:<seek point name>
                            callbacks:
                              - marker: <avatar animation marker name>
                                receiver: respondermod:<responder name>
                                user: 0
                        waiton: -1
                      - type: soundmsg
                        params:
                            receivers:
                              - 0011:<sound emitter name>
                            cmds:
                              - play
                              - setvolume
                            volume: 1
                        waiton: 0
                    nextstate: 0
                    waittocmd:
                      - key: 0 #this is the waiton value
                        msg: 0 #this is the user value
                curstate: 0
                flags:
                  - detecttrigger

So what if you want to use a callback but don't know the name of the marker? In that case you can simply leave the marker line out of your script.

                      - type: oneshotmsg
                        params:
                            receivers:
                              - oneshotmod:<seek point name>
                            callbacks:
                              - receiver: respondermod:<responder name>
                                user: 0
                        waiton: -1

This is not recommended because markers are usually not placed entirely at the end of the animation. Take for example the DoorButtonTouch animation. This makes the avatar stretch its arm, push the door button and move down its arm. The marker for this animation is placed at the point where the avatar pushes the button.

If we skip the marker the callback will happen after the avatar has put its arm down. So we still get a delay but the main action will seem to lag somewhat behind the avatar.