How to implement a camera attachment

Camera Attachment Extension is the fourth user-layer extension point. It takes full per-frame control of the camera - overriding the default first-person viewpoint with any camera behaviour you implement. It is implementable in C++ or Python and is scanned from the same user dynamic library as all other extension types.

Note

Camera Attachment is the one extension point not yet migrated to the unified parameter contract. Unlike Triggers, Actors, Player Extensions, and RenderMethods, it does not expose getParameters() / setParameters() and therefore has no editor-exposed GenericParameter configuration. Configuration is currently passed in code (for example, through the owning Player Extension’s constructor) rather than persisted and edited in the editor. Migrating it to the shared contract is planned.

Interface

Method	Description
get_camera_variables	Called every frame. Returns four vectors that define the camera pose: position, center (look-at point), up, and right.
is_dirty	Returns True if the camera parameters have changed since the last call to clear_dirty. The engine checks this each frame to avoid redundant updates.
clear_dirty	Marks the camera parameters as clean after the engine has consumed them.

Wiring the Extension

A Camera Attachment Extension is activated through the Player Extension, not directly from the editor. Override get_custom_camera_attachment in your Player Extension and return an instance of your Camera Attachment class. Return None to use the built-in first-person camera.

def get_custom_camera_attachment(self):
    return MyThirdPersonCamera()

Only one Camera Attachment can be active at a time. Returning a new instance from get_custom_camera_attachment replaces the current one.

Python Example

The following example reads the transform of any world object and uses it as the camera position. This is the approach used by the built-in “3D object pick up” sample.

import limonEngine

class ObjectFollowCamera:
    def __init__(self, api, target_object_id):
        self.api = api
        self.target_id = target_object_id
        self._dirty = True
        self._position = limonEngine.LimonTypes.Vec4(0, 0, 0, 1)
        self._center = limonEngine.LimonTypes.Vec4(0, 0, 1, 1)
        self._up = limonEngine.LimonTypes.Vec4(0, 1, 0, 0)
        self._right = limonEngine.LimonTypes.Vec4(1, 0, 0, 0)

    def get_camera_variables(self):
        matrix = self.api.getObjectTransformationMatrix(self.target_id)
        # Extract position, forward, up, right from the transform matrix
        # and populate self._position, self._center, self._up, self._right
        self._dirty = True
        return (self._position, self._center, self._up, self._right)

    def is_dirty(self):
        return self._dirty

    def clear_dirty(self):
        self._dirty = False

Note

getObjectTransformationMatrix (Python) returns the full 4x4 world transform of any object. This is the recommended method for reading object transforms that drive physics or camera position - it returns the physics-authoritative matrix rather than the interpolated editor values returned by getObjectTransformation.

Sample Extension

The engine ships with a “3D object pick up” sample implementing Camera Attachment Extension. It demonstrates:

• Reading a target object’s transform each frame via getObjectTransformationMatrix

• Forwarding the object’s position, forward, up, and right vectors directly to the camera

• Enabling third-person, orbital, or fixed-camera behaviour without any engine modification

The sample is a good starting point for any custom camera mode. It is available as part of the bundled extension samples alongside the western theme AI actor and player controller samples.

Limitations

• Camera attachment overrides the full camera pose - there is no partial-control mode.

• Perspective camera only - orthographic projection is not supported.

• The camera is attached to the player context only. A free-floating camera independent of the player is not directly supported in 0.7 (CameraObject planned).