From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Views 1.1 View Overview 1.2 Creating Views 1.3 View Properties 2 Example Cameras 3 References

Views

View Overview

The basic functionality of a camera is in a view. The CryEngine viewsystem allows switching of the current active view among multiple views. A view derives its position and orientation from an attached entity. Thus, to expand on the metaphor, a view acts as the lens of a camera.

A view can be attached to any entity. For example, you could attach a view to a character to provide a first-person view. But for modularity, flexibility, and reusability, chances are you'll want to create a distinct "camera" entity associated with the view.You can implement one for your needs or use one of the #Predefined Cameras.

Since cameras are entities, they can be installed by dragging from the Sandbox Object browser or spawning with the System function SpawnEntity.

If you choose to implement a custom camera outside of your minigame script, you can include the new camera entity in your minigame XML file, and then either manually include the entity when placing the minigame or have a call to System.SpawnEntity in your minigaime script.

If you choose to create a custom camera, you can use the #Predefined Cameras as a starting point. It is recommended that the same conventions are used for activating and deactivating the camera, and initializing and destroying it.

Creating Views

These functions in the Game table create and manipulate views. You can think of a view as a camera lens - you can set view parameters like FOV, but to move and point it, you need to attach it to an entity.

CreateView()

create a new view

DeleteView(viewID)

delete a view

SetActiveView(viewId)

sets the current active view to viewId

GetActiveView()

returns the ID of the current view

LinkViewTo(viewId, entityId)

link a view to an entity

GetLinkedId(viewId)

return the entityID view is linked to

A camera is an entity with a view attached. This is typically done in the OnInit or OnSpawn callback of the Entity Scripts.

self.view = Game.CreateView();
Game.LinkViewTo(self.view,self.id);

The camera "sees" when its view becomes active. By convention in the #Predefined Cameras we do this in a Start function:

self.origView = Game.GetActiveView();
Game.SetActiveView(view);

Also by convention, in the example cameras, we have a Stop function that restores the previous view. This allows us to switch among multiple cameras and return to the original view easily. If you implement your own cameras, it is recommended that you follow these conventions.

This gives you a minimal camera. Then you can implement its own behavior by defining an OnUpdate function or a number of entity states with OnUpdate functions.

View Properties

System has functions that operate on the current view. We provide similar functions in Game that allow operation on views by view ID's.

SetViewShake(viewId, angle, shift, duration, frequency, randomness)

Start camera shaking

ResetViewShaking()

Stop camera shaking

SetViewFov(viewId, fov)

Sets the field of view for viewId

GetViewFov(viewId)

Returns the field of view for viewId

SetViewNear(viewId, near)

Sets the near plane for viewId

GetViewNear(viewId)

Returns the near plane for viewId

GetViewPos(viewId)

Returns the position of the view camera

IsPlayingCutScene()

returns true if the view system is playing a cutscene, false otherwise

Example Cameras

There's no way to implement a camera that will satisfy every game's needs, but Blue Mars includes a number of example cameras.

The entity descriptors are listed in Game/Entities/Minigames/Cameras.

The Entity Scripts for predefined cameras can be found in Game/Scripts/Entities/Minigames/Cameras. In the Sandbox Editor object browser, the camera entities can be found under Minigames/Cameras.

Each of these cameras has Start and Stop methods:

Start()

Make the camera's view active

Stop()

Returns the active view to the previous one

For cameras that have a target:

SetTarget(entity)

These are just conventions. You can implement cameras anyway you want - you just need to use the View functions listed above. Feel free to use these cameras as they are, or use them as examples of how to implement your own cameras.

• MiniCamera - a minimal camera with no built-in behavior
• MiniAttachCamera - a camera that attaches to an entity
• MiniLookAtCamera- a camera that always looks at a target
• MiniMouseOrbitCamera - a camera that orbits a target in response to mouse movement
• MiniFollowCamera - a camera that follows a target
• MiniFollowOrbitCamera - camera the combines following and mouse orbiting
• MultiCamera - a camera that includes several of the above as separate modes and switches among them

References

Game Programming Gems has articles on camera implementation, particularly third-person cameras, in volumes 1,2, and 4.

Real Time Cameras is a comprehensive book on the subject.

See the Golf minigame for an example of usage. The ARGolfCamera is a combination of the MultiCamera & the MiniFollowOrbitCamera.