OrbitCameraController class Scene graph

Orbits the camera around a fixed target point: drag rotates, scroll or pinch dollies in and out, and a two-finger or secondary drag pans the target across the view.

The camera rides a turntable, an azimuth around world up and a polar elevation clamped just short of straight up/down, so the horizon stays level and the view never flips over the poles. Distance-scaled dolly keeps the zoom feeling constant whether the camera is close or far.

With an OrthographicProjection, where moving the eye does not change the image size, dolly scales the projection's OrthographicProjection.zoom by the same ratio instead, so zoom set in code or an inspector is kept and scaled from. The eye holds the distance it had when the controller started driving that projection, so the clip planes stay where they were authored.

Attach it to a node that also carries a CameraComponent. Drive it with a CameraControls widget, or call orbitBy / dollyBy / panBy directly.

Inheritance

Constructors

OrbitCameraController({Vector3? target, double distance = 6.0, double azimuth = 0.0, double polar = 0.3, double minDistance = 0.1, double maxDistance = double.infinity, double minPolar = -_polarLimit, double maxPolar = _polarLimit, double rotateSpeed = math.pi, double dollySpeed = 0.15, double panSpeed = 1.0, double scrollSensitivity = 1 / 120, double smoothing = 0.12})
Creates an orbit controller framing target from distance at the given azimuth and polar angles (radians).

Properties

distance → double
Distance from target to the camera.
no setter
dollySpeed ↔ double
Proportional dolly rate; the distance changes by exp(-amount*dollySpeed) so a step feels the same near or far.
getter/setter pair
enabled ↔ bool
Whether this component's update hook runs each frame.
getter/setter pairinherited
hashCode → int
The hash code for this object.
no setterinherited
isAttached → bool
Whether this component is currently attached to a node.
no setterinherited
isLoaded → bool
Whether onLoad has completed.
no setterinherited
isMounted → bool
Whether the owning node is part of a live scene graph.
no setterinherited
maxDistance ↔ double
getter/setter pair
maxPolar ↔ double
getter/setter pair
minDistance ↔ double
Closest and farthest the camera may dolly. minDistance must be > 0.
getter/setter pair
minPolar ↔ double
Elevation clamp (radians), kept just inside +-pi/2 so the view never flips over the poles.
getter/setter pair
node → Node
The node this component is attached to.
no setterinherited
panSpeed ↔ double
Pan distance as a multiple of the drag fraction times the orbit distance.
getter/setter pair
rotateSpeed ↔ double
Radians of orbit per view-height of drag.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollSensitivity ↔ double
Dolly steps per unit of scroll delta.
getter/setter pair
smoothing ↔ double
Approximate time in seconds to settle after input stops (reach ~1% of the remaining offset). Zero moves instantly with no easing.
getter/setter pairinherited
target ↔ Vector3
The point the camera orbits (its eased, current value).
getter/setter pair
viewportSize ↔ Size
The size of the view driving this controller, in logical pixels.
getter/setter pairinherited

Methods

clampDeltaSeconds(double deltaSeconds) → double
Clamps a frame delta so a stall or a paused view does not teleport the camera when it resumes.
inherited
cloneFor(Node cloneOwner) → Component?
Returns a copy of this component for cloneOwner, the Node.clone counterpart of the owning node, or null to not carry the component to clones (the default).
inherited
dollyBy(double amount) → void
Dollies toward (amount > 0) or away from (amount < 0) the target, proportional to the current distance and clamped to the distance limits.
fixedUpdate(double fixedDt) → void
Called once per fixed physics step while the component is mounted, enabled, and loaded. fixedDt is the fixed timestep of the surrounding PhysicsWorld, not the frame interval.
inherited
frame(Aabb3 bounds, {double margin = 1.5}) → void
Frames bounds by centering the target and dollying to fit its bounding sphere, with margin padding.
handleDragUpdate(Offset delta) → void
A primary drag (one finger, or a left-button mouse drag), in logical pixels. The default rotates/looks; override to remap.
override
handleKeyEvent(KeyEvent event) → bool
A keyboard event; controllers that move on keys track held state here. Returns true when the key is consumed (so the driver can stop it propagating and the platform does not beep at a held movement key).
inherited
handleScaleUpdate(double scaleFactor, Offset focalDelta) → void
A two-plus finger gesture: scaleFactor is the incremental pinch factor since the last update (>1 spreading, <1 pinching) and focalDelta is the centroid movement in logical pixels.
override
handleScroll(double scrollDelta) → void
A scroll/wheel notch; scrollDelta follows the platform sign (positive scrolling down/away).
override
handleSecondaryDragUpdate(Offset delta) → void
A secondary drag (right-button mouse drag), in logical pixels. The default pans where the controller supports it.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onAttach() → void
Called when this component is added to a node.
inherited
onDetach() → void
Called when this component is removed from a node.
inherited
onLoad() → Future<void>
Optional asynchronous setup, such as loading an asset.
inherited
onMount() → void
Called when the owning node enters a live scene graph.
inherited
onUnmount() → void
Called when the owning node leaves a live scene graph.
inherited
orbitBy(double deltaAzimuth, double deltaPolar) → void
Rotates the orbit by deltaAzimuth (around world up) and deltaPolar (elevation), radians. Polar is clamped to [minPolar, maxPolar].
panBy(Offset fraction) → void
Pans the target across the view by fraction of the viewport (its components in [-1, 1]), scaled by distance so the world tracks the drag.
releaseInput() → void
Releases any held input (call when the driving view loses focus so keys released elsewhere do not stick).
inherited
settleResponse(double smoothingSeconds, double deltaSeconds) → double
smoothingResponse for an explicit smoothingSeconds, so a controller can settle different quantities (look versus movement) at different rates.
inherited
smoothingResponse(double deltaSeconds) → double
The fraction of the remaining offset to consume this frame for a frame-rate independent exponential settle. One when smoothing is zero.
inherited
toString() → String
A string representation of this object.
inherited
update(double deltaSeconds) → void
Called once per frame while the component is mounted, enabled, and loaded. deltaSeconds is the elapsed time since the previous tick. A traversal visits each component at most once. Removing this component or an earlier sibling is safe. A component inserted before the current traversal position starts on the next frame. Reordering component or child lists during traversal is unsupported.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited