Difference between revisions of "Editor Camera"

From Wolfire Games Wiki
Jump to: navigation, search
m (Camera instances in other scripts)
m (Callable functions and data available inside camera scripts)
Line 14: Line 14:
 
== Callable functions and data available inside camera scripts ==
 
== Callable functions and data available inside camera scripts ==
  
The editor camera script gets an instances of the camera itself (a variable defined as <code>Camera@ camera</code>), so it can call functions on the <code>Camera</code> interface.
+
The editor camera script gets an instances of the camera itself (a variable defined as <code>Camera@ camera</code>), so it can affect the active camera.
  
 
It also gets an instance of the editor camera controller object (a variable defined as <code>CameraObject@ co</code>), so it can access properties that are editor specific.
 
It also gets an instance of the editor camera controller object (a variable defined as <code>CameraObject@ co</code>), so it can access properties that are editor specific.

Revision as of 04:18, 19 November 2017

Overview

Cameras let you control where the player's view is positioned and what it is pointing at. Same with the editor camera.

They also let you apply effects like depth of field, the view angle (FOV), and camera shake.

Note: This documentation mostly applies to the editor camera script. You can access cameras from other scripts (level scripts, hotspots, character scripts), and may not need to change the editor camera script in order to get the functionality you're looking for!

TODO: More useful description. Multiple cameras - are those even a thing? How does it work for split-screen?

Documentation

Callable functions and data available inside camera scripts

The editor camera script gets an instances of the camera itself (a variable defined as Camera@ camera), so it can affect the active camera.

It also gets an instance of the editor camera controller object (a variable defined as CameraObject@ co), so it can access properties that are editor specific.

A list of functions, data, etc, is created automatically whenever you run the game, in a file on your hard drive. This lists some of the external code you get "for free" and can call from inside a camera script. (Some of this code in this list is not usable from a camera script - see the links below for more info).

  • Windows: My Documents\Wolfire\Overgrowth\aslevel_docs.h
  • Mac: ~/Library/Application Support/Overgrowth/aslevel_docs.h
  • Linux: ~/.local/share/Overgrowth/aslevel_docs.h

This documentation will change with each version of the game, so keep checking back on this aslevel_docs.h file to see the most up to date information.

There are also wiki pages which have more detailed documentation many of these functions. These pages have a danger of going out of date, but give more detailed documentation on some of the code:

Camera instances in other scripts

The editor camera controller is not exposed to other scripts at all. It is only accessible to the engine, and in the editor camera script.

The camera object (that actually affects the screen) is exposed to other scripts as instances of the Camera class (as Camera@ camera).

How to create a custom camera script

The camera script always has this path: Data/Scripts/cam.as

If you are overriding this in a mod, it will have this path: Data/Mods/<your_mod_name>/Scripts/cam.as

Camera script hook functions

All functions inside a camera script are required

Init function

void Init() { }

Required

Init is called when the camera is first loaded, upon level load.

Be careful, this may be called before some objects or script params are present in the level.

It is most useful for setting initial values for file-scope angelscript state.

Update function

void Update() { }

Required

Update is called regularly by the engine so you can perform work.

It may be useful to do initialization once in this function, if you need to delay camera updates until other objects have loaded.

Be careful to keep this function short, sweet, and fast. Update gets called 120 times a second as of the time of this writing. TODO: Is this accurate for camera scripts?

FrameSelection function

void FrameSelection(bool increased_distance) { }

Required

FrameSelection is called when the "frame selection" action called in editor. This is invoked in one of two ways:

  • Via hotkeys (F or SHIFT + F)
  • Via the Go To Selected action in the menu. Top Bar -> Selected -> Go To Selected

The increased_distance parameter will be set to true if the desired action is to frame all selected items within the camera
(the F hotkey, or the Go To Selected menu item set this to true).

The increased_distance parameter will be set to false if the desired action is to teleport to the selected items
(the SHIFT + F hotkey sets this to false).