ramokz/phantom-camera

👻🎥 Control the movement and dynamically tween 2D & 3D cameras. Built for Godot 4. Inspired by Cinemachine.

phantom-camera's Issues

Initial 2D Example Scene

Add release for 0.5

Path Track Follow

Problem

PhantomCamera3D is set to follow either nothing or a specific Node where #40 adds support for specifying the specific Follow logic.

But there are use cases where wanting to just follow along a path is another desired option. While this is possible to do so programmatically, it would be nice to have a built-in system that clamps a PhantomCamera's movement to a certain path.

Proposed Solution

Add a new property to the Follow option list from #40 that allows for using either a Path2D or Path3D to restrain the PhantomCamera's position to that path. In addition to this, it ought to also have a property to define what % along the path it should be placed on.

Camera Priority System

Default Follow Offset

Add release for 0.2

Features to List & Document

• Look At Modes
  • Disabled
  • Mimic
  • Simple Look At
  • Group Look At
• Follow Group 2D
  • Min Zoom
  • Max Zoom
  • Zoom Margin
• Follow Group 3D
  • Distance Parameter
  • Auto Distance
    • Min Distance
    • Max Distance
    • Auto Distance Divisor

Camera Deadzone Support

Problem

As the PhantomCamera follows a target Node follows a target, it will always try to keep itself centred on its target.

There are cases where having the camera not move until a certain amount of movement has been done by the target Node.

Proposed Solution

Add a property to PhantomCamera that adds a movement threshold so that a follow movement won't be triggered until the target exceeds that threshold.

Add a property to PhantomCameras to trigger a transition when instantiated

Context

When PhantomCameras are instantiated, they will currently not trigger a transition. However, this might not be desired in some instances when, for example, instantiating a scene with a PhantomCamera.

Proposed Solution

Add an Auto Transition property to PhantomCameras nodes that allow them to trigger a transition if its priority is the highest in the scene when instantiated.

Camera Grid View

Problem

When previewing a PhantomCamera (based on #24) it would help to see an optional grid view of the camera, such as a 9-grid.

Also supports #29 by being able to see Dead Zone areas in the preview.

Proposed Solution

Show an optional grid overlay, with a few options, enabled from the PhantomCamera property list.

Current thinking is a UI overlay, but still pending further thoughts.

Disabled Follow State

Problem

Part of #40, having a follow option set to default, or in this case disabled, when initially adding a Follow Target will prevent any automatic, and potentially undesired, repositioning.

Proposed Solution

Add an option to disable any follow logic by default for a PhantomCamera when setting a Follow Target node.

Glued Follow Mode

Problem

Part of #40, to support use cases with very simple follow requirements, Glued Follow would simply stick to the position of its target with minimal property options.

Proposed Solution

Add a Glued Follow option that sets the PhantomCamera to simply stick to its Follow Target. The only parameter for this mode is Damping to ease the positional changes.

Support 2D Phantom Camera

Add release for 0.1.1

Individual Phantom Camera Easing Property

Add release for 0.3

Preview PhantomCamera without modifying priority

Problem

When modifying a position or rotation of a PhantomCamera, in the Editor, you won't see the framing of it until it becomes active.
In order to preview what it sees / frames, you have to manually set its priority to the highest value. This is not only tedious when changing a scene or moving PhantomCameras around, but can also pose a risk due to forgetting to revert the priority value back to what it should be.

Proposed Solution

Adding a property button that forces a PhantomCamera to become active – in spite of not having the highest priority. This would only be usable in the Editor and disabled during runtime to avoid any unintended behaviour.

Viewfinder should state if it's currently being manually set to active in the editor to prevent confusion with the viewfinder saying one thing, while runtime says something else.

Simple Follow Mode

Problem

Part of #40, would cover the most typical use case. Contains simple options to offset the target position and damping to provide a bit of flexibility, but without adding the same level of complexity as #78.

Proposed Solution

Add a Simple Follow option that has options for Target offset and Damping.

Distance Offset

Problem

When a PhamtomCamera follows a target's position, that position is based on that target's position.
To offset that position, so that the PhantomCamera isn't placed inside the target, there's an additional parameter that offsets that position. In practice, all that it does is offsetting the point that the camera is looking at.

The proposal here is to add another property that, on top of the PhantomCamera's own target offset, allows for setting a forward distance to that offset. Mainly to allow for an easy to define distance parameter to the target.

Proposed Solution

Add a new property named Distance that increases the forward vector of the PhantomCamera.

Inactive PhantomCamera Update Mode

Problem

When PhantomCameras are inactive, they currently stick to their follow / look at logic every frame. This can have some performance implications if many gets added to a scene.

Proposed Solution

Allow for an option to decide how frequently a PhantomCamera should be updated. Proposed ideas are:

• Always (default), least performant but most accurate
• Never, only updating once it becomes active
• Exponentially, the more PhantomCameras in the scene, the fewer updates
• Fixed, checks based on a user defined interval.

Edit:
Descoped to only support Always and Never for now.

Visuals for Feature list in Readme file

Problem

The repo's Readme file contains a list of example features. Currently, they're just text descriptions, which are not easy to understand without any visual references.

• Follow (2D)
• Follow (3D)
• Look At (3D)
• Tween (2D)
• Tween (3D)

Solution

Provide animated examples below each feature sub-header that exemplifies what they mean.

Transition Duration per Phantom Camera

Phantom Camera Manager

Documentation 0.1

Context

Documentation to cover how the general aspects of the plugin work and how to use.

Solution

Main Page

About

• Banner & Icon Image
• Short description (About panel)
• Long description (readme)
• Roadmap, link to project page for project
• Installation guide

FAQ

• About Multiple PhantomCameraHosts
• How to contribute

Misc

• License
• Credit / Inspiration

Wiki

Phantom Camera

Editor

• How to use it in the scene

Properties (Editor)

• Priority
• Follow Target
• Look At Target Property
• Tween Properties

Code Usage

• How to use set_priority() to change PhantomCamera target

Phantom Camera Host

• What it is & how it works
• Notes & caveats

Multiple Follow Options

Problem

The current Follow property is effectively a case of “do or do not follow”.

While this enables a PhantomCamera to stick to another Node's positional changes, it's also extremely limited in terms of what you can do with it.

Ideally, there should be more flexible options to allow a greater variety of follow logic. This also opens up for other follow behaviour, such as #31.

Proposed Solution

Add the following Follow behaviours as a dropdown (enum) property option:

• Disabled (Default) #75 – Disables any follow logic, a Follow Target may still be set
• Simple Follow #77 – Sticks to the target Node but features offset parameters (how the system currently works), #28 will be affecting this
• Framed Follow #78 – Similar to Follow Follow but with many additional options, #28 will be affecting this
• Glued Follow #76 – Position follows the exact position of the targeted Node
• Path Track Follow #31 – Follows a given Path2D or Path3D

Phantom Camera Transition

Transition Resource

Problem

Currently, every PhantomCamera instance's Tweening property has to be entered manually. Meaning if you want to use the same transition, easing and duration for different PhantomCameras it can be a chore to set up but much more so should changes be required.

The proposal here is to allow for a shared resource that can be reused between different PhantomCameras.

Proposed Solution

Add an option to create and save a custom PhantomCameraTween resource that can be reused between PhantomCameras.

Look At Group

Problem

PhantomCamera3D is currently able to Look At an individual Node in a scene.

But there are use cases where keeping multiple Nodes in view at the same is desired.

Proposed Solution

Add a new Look At property type to allow multiple Nodes to become the Look At target. The average position would then be the PhantomCamera's position Look At position in effect.

Camera Damping

Problem

PhantomCameras currently follows its Follow target the instant the target's position changes. However, there are many use cases where wanting a slight delay to simulate a more realistic camera operator's movement, or less abrupt changes to the camera, is desired.

Damping the Follow movement would give a bit of weight to the PhantomCamera's follow logic. Providing a more flexible solution and end experience.

Proposed Solution

Add a property to PhantomCamera that dampens the follow movement, effectively adds a small delay to the follow logic.

Initial 3D Example Scene

Context

To provide a simple playable example scene using CharacterBody3D to move round in.
Scene is meant to demonstrate a few different use cases for the plugin, in addition to how it can be applied in practice.

Solution

Examples to cover the following interaction / state changes:

• Zone Trigger
• Input Trigger

Add tooltip description to PhantomCamera properties

The Problem

All the properties in PhantomCamera classes currently don't have any descriptions for what they do. So the only way to know what each property does is by looking at the wiki documentation, the source code or trial and error.

Proposed Solution

Add a description to each property that explains what each does.

Look At Offset

Improve 3D Example Scene

Problem

The current 3D example scene works for simple demonstration purposes.
But it is a bit barebone and could use some further polish.

Proposed Solution

Add further visual improvements, environment details and gameplay mechanics.

Editor UI

Problem

As more PhantomCameras get added to a scene, it will increasingly become difficult to keep track of all of them without digging through a long hierarchy list.

Issues such as knowing what each PhantomCamera's priority, Follow/Look At target etc. can quickly become challenging.

Proposed Solution

A custom Editor UI that lists all PhantomCameras in the active scene.
With some options to see and modify top level properties such as:

• Priority
• Follow Target
• Follow Type (based on #40)
• Look At Target

In addition to functional behaviour such as:

• Locate the PhantomCamera in a scene
• Locate its Follow Target
• Locate its Look At target
• Preview PhantomCamera (based on #24)

Animate Look At target during pcam transition

Multi PhantomCameraHost / Split Screen Setup Support

Context

Idea is to support split screen views using multiple PhantomCameraHost - each attached to separate Cameras (2D or 3D).

Proposed Solution

When more than 1 PhantomCameraHost is added to a scene, add a dropdown property option for each PhantomCamera (to use within the Editor), which allows the user to decide which PhantomCamera belongs to which PhantomCameraHost. Each PhantomCameraHost will then only respond to the changes for the PhantomCameras that are assigned to it.

Apply Look At Target to Camera

Camera Springarm / 3rd Person Follow

Problem

PhantomCamera3D is currently living freely in space as it moves around. While this is fine in many cases, there are also scenarios where there's a desire to make the camera unable to go through colliders in a scene, which would otherwise cause it to go out of bounds and through geometry. Leading to potentially undesired results.

Proposed Solution

Add a new follow mode parameter to PhantomCamera3D that functions like a SpringArm to provide collisions. Essentially working as a base 3rd person follow mode.

Framed Follow mode

Problem

Part of #40, a more advance version of #77 with additional properties for more complex framing setup.

Proposed Solution

Feature options:

• Adjustable horizontal and vertical Dead Zones – meant to keep the camera still until the target exit it
• Camera frame preview – to preview and more intuitively adjust how large the Dead Zones are
• Automatically make camera follow its target when it moves outside the Dead Zones
• Enable Dead Zone preview while playing the game – IMPORTANT Toggle to only show in editor play, and not when exported as a standalone build](https://docs.godotengine.org/en/latest/tutorials/export/feature_tags.html)
• Distance property, defines the camera distance away from the target
• Auto Look At – Enables the camera to always have the target in view, but will be overruled if a Look At target is applied

Individual Phantom Camera Transition Property

Align Phantom Camera with View

Problem

When instantiating a new PhantomCamera3D, it's set to its default position and rotation. To adjust it, you would either need to set a Follow/Look At property or manually position and rotate it.

The former is not necessarily a desired outcome, and the latter can be a bit tedious to mess around with beyond simple changes.

The proposal here is to set a PhantomCamera3D's position and rotation to the current viewports position and rotation, with the intent to speed up the initial framing process.

Proposed Solution

Add a button prompt in the property panel for PhantomCamera3D that aligns its positional and rotational value with that of the viewport's.

Camera Frustum Preview

Problem

While you can see where all PhantomCamera3Ds are positionally located, you can't see what direction they're looking at. Meaning, you would have to either preview the PhantomCamera3D by making it the active one (cumbersome), or judge it based on its rotational values (super obscure and also cumbersome).

While this isn't game breaking by any stretch, it does mean that accidental rotational values can be applied without any obvious way of spotting it – particularly when there are many in a scene.

Proposed Solution

Add a frustum preview that shows the forward direction of a PhantomCamera3D using either SurfaceTool or ArrayMesh.

ImmediateMesh is also an option should there be a need to change the frustum based on, e.g., any future FOV property options as part of the PhantomCamera property list. But since it's rendered every frame, it would needlessly reduce the performance while in the Editor.

Timeline Transitions

Problem

Currently, the only suggested way to modify a PhantomCamera's priority, and in turn where the Camera2D / Camera3D is and what it's looking at it, is to call the method set_priority.

But there are many, if not most, instances where being able to do this via a Timeline, when doing cutscenes or more bespoke animations in general, is a desire approach for using this. While it's possible to adjust this from the timeline, it's a bit overwhelming with the amount of properties to choose from and knowing which to adjust.

The idea here is to explore how to simplify that workflow as much as possible to allow for an equally simple code and timeline approach.

Proposed Solution

TBD

Disabled Look At Mode

Problem

Part of #62, to avoid any sudden property changes when adding a node to the Look At Target property, a default value set to None ought to be applied. This can then be overridden with another mode type.

Proposed Solution

Add a default value of None to the Look At Mode by default when supplying a valid node to the Look At Target property.

PhantomCamera Debug UI

Problem

In the Editor, it can be tricky to know which PhantomCamera is active, what priority it has, what the second-highest priority is etc. without selecting various PhantomCameras in the hierarchy.

The proposal is to have a togglable debug UI that will show relevant information when actively working with the plugin.

Proposed Solution

Add a debug UI that enables will show the following. Should be attached to the PhantomCameraHost:

• Active PhantomCamera's name
• Active PhantomCamera's priority
• Second-highest priority int value

Note: Priority for visual noise is key. It needs to be easily accessible, but simultaneously show enough to remain useful.
This can be expanded upon should more feature become relevant to this.

Select PhantomCameraHost owner from PhantomCamera

Problem

As more debug options gets added to the plugin, it can become a frequent thing to go to a PhantomCameraHost to change debug and other settings.

The proposal here is to add a way to select the PhantomCameraHost from each PhantomCamera

Proposed Solution

Add a property prompt to PhantomCameras that shows and allow for selecting its PhantomCameraHost.

Multiple Look At Options

Problem

Similar to #40, there are use cases where having multiple Look At options for a PhantomCamera3D.
While there are currently three options Don't Look At, Fixed Look At and Look at Group, there are other types that are worth including.

Proposed Solution

The new options to include are:

• Disabled (Default) #80 – Disables any rotation logic, a Look At Target may still be set
• Framed Look At #81 – Allows for a variety of options such as offset (#21), damping (#28) and more.
• Fixed Look At – What the current system is using, glues the PhantomCamera3D to look at the target Node
• Mimic Look At #79 – Copies the rotational value of the target
• Group Free Look At #38 – Allows for looking at multiple nodes at once. The mode effectively attempts to keep all of them in view.

Framed Look At Mode

Problem

Part of #62, provides a more advance set of property options for a Look At target.

Proposed Solution

TBD

Handle Multiple Phantom Camera Hosts in scene

Context

To solve errors when adding multiple PhantomCameraHosts to a scene, a temporary solution here is to only support one Host in the scene. This should also be the desired outcome state as multiple cameras ought to, though there might be other use cases, only be for when wanting to do a split view / split screen setup.

Solution

• Forcefully remove any additional PhantomCameraHosts that are added to a scene where one already exists.
• Print error statement to inform the user why the above happened and point to future fix / enhanced support.

Proper Multi PhantomCameraHost support will be added in #26.

Mimic Look At Mode

Problem

Part of #62, adds support for use cases where you would want the Look At logic to simply mimic the target node's rotational properties.

Proposed Solution

Add a Look At mode called Mimic that copies a given Look At target's rotational value.

Add release for 0.4