Latest revision as of 17:24, 1 July 2018

Introduction

The 'OneShotMod' avatar animations are examples of 'advanced' avatar animations that are triggered by a script. They are mostly used when the avatar interacts 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 the realism a great deal.

Those animations must be triggered through Alcscript. Note that 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 'Using Non-Global Animations' section 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 LinkToAge message 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 to pass the PythonFileMod 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.prp
Name: LinkOut
Callback Marker: touch
URU Example: Phil's Relto book in spyroom_District_spyroom.prp

Door button

This is the regular wall-mounted button press animation, but it can also used for other things like for touching the Journey cloths, or any action that requires a large button on a wall.

Dimensions:

Animation: GlobalAnimations_District_*DoorButtonTouch.prp
Name: DoorButtonTouch
Callback Marker: DoorButtonTouch
URU Example: Relto hut door in Personal_District_psnlMYSTII.prp

'Flat' button

This one is for pressing the small horizontal buttons found in many Uru ages.

Dimensions:

Animation: GlobalAnimations_District_*ButtonTouch.prp
Name: ButtonTouch
Callback Marker: TouchButton
URU Example: Fountain light buttons Neighborhood_District_nb01.prp

Sitting regions

Used for all the chairs and benches, this doesn't need to be triggered explicitly in AlcScript. They are triggered automatically like the ladders.

Dimensions:

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', where the hand lightly brushes the lever handle. There are two animations depending whether the lever is on the 'up' or 'down' position. Consequently, two one-shot-animation empties are needed in your scene - and they are co-located.

Dimensions:

Animation: GlobalAnimations_District_*BlndFrntLeverUp.prp
Name: BlndFrntLeverUp
Callback Marker: LeverUp

Animation: GlobalAnimations_District_*BlndFrntLeverDown.prp
Name: BlndFrntLeverDown
Callback Marker: LeverDown

URU Example: Shades lever in Personal_District_psnlMYSTII.prp

NOTE: The animation 'BlindLeverUp' is actually not used for the shades lever in the Relto hut. It grips a handle on a lever, and it approaches the lever from a 45-degree angle.

Scopes

All scopes in Uru work 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.

The animations do not have callback markers. Instead, it requires a PythonFileMod (using the generic xTelescope script and a MultistageBehMod) to trigger the appropriate phases of the animation - as well as turning on the scope-view camera. [As of April 2009, this is not supported in the PyPRP plugin.]

Dimensions:

Animation: GlobalAnimations_District_*ScopeGrab.prp
Name: GlobalScopeGrab
Animation: GlobalAnimations_District_*ScopeHold.prp
Name: GlobalScopeHold
Animation: GlobalAnimations_District_*ScopeRelease.prp
Name: GlobalScopeRelease

URU Example: Scope in spyroom_District_spyroom.prp

Rotating doors

Most doors in Uru are "Star Trek"-style sliding doors. However, there are regular rotating doors, which are 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. To prevent issues like this, the rotating door requires a PythonFileMod (using the xStandardDoor script and a MultistageBehMod). Plus the age requires SDL variables to track the state of the door, and from which side it was openend.

These animations are not global - see the notes below on how to incorporate 'local' animations into your age. Also, there are two 'open' animations (depending on which side of the door you are standing), but only one close animation. The door animations (rotating the door handle first, then rotating the door) are tricky to align to the avatar animation. Open the Blender file below to examine the animation keys for the door and handle. Note: the close animation uses a separate animation sequence for the door than the open animation.

Dimensions:

Animation: Teledahn_District_*NoxiousCaveDoorPullOpen.prp
Name: NoxiousCaveDoorPullOpen
Callback Marker: DoorOpen
Animation: Teledahn_District_*NoxiousCaveDoorPushOpen.prp
Name: NoxiousCaveDoorPushOpen
Callback Marker: DoorOpen
Animation: Teledahn_District_*NoxiousDoorClose.prp
Name: NoxiousDoorClose
Callback Marker: action

URU Example: Catwalk door and outer door in Teledahn_District_tldnSlaveShroom.prp

Relto Bahro Poles Book

This is a slight variant of the common Linking Book animation. Here, the avatar has to kneel to use 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.

However, as with the linking book, a one-shot mod is not appropriate for this animation.

Dimensions:

Animation: GlobalAnimations_District_*FishBookLinkOut.prp
Name: FishBookLinkOut
Callback Marker: touch

Floor Lever

This lever protrudes from the floor and is angled toward the avatar. It has a vertical handle, which the avatar grabs ahold of and pulls the lever toward itself, then releases it. The lever slowly returns to the original position.

Dimensions:

Animation: GlobalAnimations_District_*ShooterTrapActivate.prp
Name: ShooterTrapActivate
Callback Marker: LeverBack

URU Example: Pillar levers in Kadish_District_kdshPillars.prp

Insert KI

When activated, this animation raises the avatar's KI hand (their left) and inserts it into a slot, pauses, then removes the hand.

Dimensions

Animation: GlobalAnimations_District_*InsertKiHand.prp
Name: InsertKiHand
Callback Marker: HandIn

URU Example: Nexus KI slot in Nexus_District_nxusBookMachine.prp

Floor Pedal

This will cause the avatar to press its left foot down on a pedal.

Dimensions

Animation: "GlobalAnimations_StepOnFloorPlate"
Name: StepOnFloorPlate
Callback Marker: PlateDown

URU Example: Gahreesen's large power gear release pedals in Garrison_District_grsnWellSecondFloorGearRoom.prp

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).

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"
Callback Marker: "LeverForward"
Animation: "Teledahn_ClutchLeverBackward"
Callback Marker: "LeverBackward"

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"
Callback Marker: "ButtonDown"

"Get in the bucket
Animation of the avatar climbing into the bucket in Teledahn.
Animation: "Teledahn_GetInBucket"
Callback Marker: "Snd"

"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"
Callback Marker: "Snd"

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 in the ZIP file 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.

• Blend File Only: File:AvatarAnimations.blend
• Mirror (ZIP with blend and Python files): AvatarAnimations.zip (174kb) - Version 0.4 -- September 23 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.

Known issues:

• The scope animation is only done as a one-shot animation. It needs to be a MultistageBehMod. Consequently, the avatar will revert back to the standing idle animation after touching the scope.
• The rotating door example only supports the door-pull-open and door-push-close animations. It does not currently use the door-push-open animation. Also, it currently does not save the state of the door.

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. Set to true to let the player keep control of the avatar while it attempts to move to the seek point. Needed for "reversable".

• reversable: Default = False. Set to true if you want the player to be able to "cancel" moving to the seek point and the entire animation.

• 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.

Using Non-Global Animations

Some of the animations listed above are not part of the globally available avatar animations. These can be used in your age, but it requires creating a Python file - the animations need to be paged in when your age is loaded into URU, and subsequently paged out when leaving your age. If the animations are not paged out when you revisit your age - or the age you 'borrowed' the animations from - URU will freeze after loading.

Here are the steps to using these non-global animations in your age:

• Using PlasmaShop, create a new PAK file and name it after your age (e.g. AvatarAnimations.pak).

• Next, create a new Python file and save it with the same name as your age (e.g. AvatarAnimations.py).

• In the Python file, rename the Python class to your age (e.g. class AvatarAnimations).

• In the Python file, define a global variable above your class to store the names of the animation 'districts'. As an example, here's a variable that stores the names of the door open/close animations from Teledahn:

gPages = ['FemaleNoxiousCaveDoorPullOpen',
    'FemaleNoxiousDoorClose',
    'MaleNoxiousCaveDoorPullOpen',
    'MaleNoxiousDoorClose']

NOTE: you must load both the Male and Female versions of the animations.

• In the __init__ method, add a declaration of the global near the top, and add a call to the function PtPageInNode() at the bottom, using the global variable as the argument. For example:

    def __init__(self):
        global gPages
        ptResponder.__init__(self)
        self.id = 1770000
        self.version = 1
        PtPageInNode(gPages)

• Add a __del__ method which loops through the pages listed in the global variable and calls the PtPageOutNode() function on each page. For example:

    def __del__(self):
        global gPages
        for page in gPages:
            PtPageOutNode(page)

• Save your Python file, then add it to your PAK file.

• Exit PlasmaShop.

Now your age can reference the non-global animations - and without crashing URU!

NOTE: The suggestion to use the FNI file properties 'Nav.PageInHold <animation name>' will cause a crash when attempting to link to the age that you borrowed the animation from. So, please use the above Python code to safely add the animation to your age.