Revision as of 23:02, 27 March 2009

Defining a Camera

To create a camera, simply add a new camera object in blender, name it, and then add an alcscript defining that camera's properties. PyPRP currently supports 5 types of camera brain.

Note: You can change the field of view of the camera by going to the Editing panel (F9) and setting its Lens value on the Camera pane. The lower the lens value, the wider the field of view.

Fixed

The "fixed" camera type will stay fixed at the location it has in blender, and rotate to face the avatar. (if followlocalavatar is set) The "poa" setting must be set on fixed cameras. POA stands for Point On Avatar. This is used to define where on the avatar the camera should look at. If POA is set to 0,0,0 the camera will look at the avatar's feet. The usual POA is 0,0,6 which will cause the camera to look at the avatar's head.

Circle

The "circle" camera type constrains the camera to a circular area whose radius is defined by the clip distance setting on the blender camera. (don't ask me why they did it this way :P) The POA must be defined on a circle camera, and the "circleflags" are used in place of the normal "flags".

Firstperson

The "firstperson" camera type seems to follow the rotation of the local avatar. The "offset" setting must be set on a firstperson camera. If the offset is 0,0,0 the camera will be looking out from the avatar's feet. If the offset is 0,0,6 the camera will be looking out from the avatar's head.

Avatar

The "avatar" camera type is the normal third person camera. The avatar camera will attempt to move to the location defined by the offset, and look at the avatar's poa. The maintainLOS flag should be set on avatar cameras, or the camera will pass through walls.

Simple

The "simple" camera type just looks out from wherever the camera's sceneobject is. It should be used for animated cameras.

<blender camera>:
    camera:
        animated: <1 | 0>
        transitions:
          - velocity: 50
            poaveloctiy: 50
            accel: 10
            decel: 10
            poaaccel: 10
            poadecel: 10
        brain:
            type: <fixed | circle | firstperson | avatar | simple>
            velocity: 50
            poaveloctiy: 50
            accel: 10
            decel: 10
            poaaccel: 10
            poadecel: 10
            xpanlimit: 0.8         # how much the camera can be horizontally panned by the user (right click + drag)
            zpanlimit: 0.8         # how much the camera can be vertically panned by the user (right click + drag)
            poa: 0,0,6
            offset: 0,6,6
            flags:
              - cutpos             # camera "cuts" to intended location instantly, instead of approaching smoothly
              - cutpoa             # camera "cuts" to intended rotation instantly, instead of turning smoothly
              - cutposonce         # cuts to position once, then resumes smooth approach
              - cutpoaonce         # cuts to rotation once, then resumes smooth look at
              - followlocalavatar  # camera tries to look at the local avatar + poa
              - maintainLOS        # causes the camera to move toward it's target to avoid physical obstructions
            circleflags:
              - lagged
              - absolutelag
              - farthest           # circle camera stays as far away from the avatar as permitted by it's bounds
              - circlelocalavatar  # the circle camera equivalent of followlocalavatar

Here is an example of a simple camera alcscript. This is all that is required to define a fixed camera.

<blender camera>:
    camera:
        brain:
            type: fixed
            xpanlimit: 0.8
            zpanlimit: 0.8
            poa: 0,0,6
            flags:
              - followlocalavatar

Controlling Cameras

Cameras can be activated with special regions called camera regions. When the avatar enters a camera region the camera with the name specified will be activated. When the avatar leaves a camera region, the camera settings will revert to their previous state.

<region name>:
    region:
        type: camera
        camera:
            messages:
              - newcam: <camera name>

For advanced users, cameras can also be activated using messages, generated by any logic event. (region enter, click, facing, etc) Below is an example responder, which, when activated, will activate the specified camera.

<any object>:
    logic:
        actions:
          - type: responder
            name: <responder name>
            responder:
               states:
                - cmds:
                   - type: cameramsg
                     params:
                        cmds:
                         - regionpushcamera
                         - respondertrigger
                        newcam: <camera name>
                     waiton: -1
                  nextstate: 1
                  waittocmd: 0

Animating Cameras

If you want an animation to take complete control of a camera, you should use a simple camera with these settings, and animate the camera object like you would any other object. (the animation segment is included to show that it is still necessary)

<camera with IPO>:
    camera:
        animated: 1
        brain:
           type: simple
            xpanlimit: 0
            zpanlimit: 0
            flags:
             - cutpos
             - cutpoa
    animations:
        - name: <animation name>
          autostart: 0
          loop: 0