Godot Native Camera Plugin

A Godot plugin that provides a unified camera capture interface for Android and iOS using native platform APIs. It enables real‑time camera frame streaming directly into Godot with configurable resolution, rotation, frame skipping, horizontal/vertical mirroring, and optional grayscale output.

Key Features:

• Unified GDScript API for Android and iOS
• Enumerate available cameras and their supported output sizes
• Start and stop native camera frame streaming
• Receive raw frame buffers or ready‑to‑use Image objects
• Configurable resolution, rotation, frame skipping, horizontal/vertical mirroring, grayscale capture, and post-capture scaling
• Auto-upright orientation correction — automatically rotates every frame to be upright as the device is tilted, without any manual rotation tracking in your game code
• Designed for real‑time use cases (CV, AR preprocessing, custom rendering)

Installation

Before installing this plugin, make sure to uninstall any previous versions of the same plugin.

If installing both Android and iOS versions of the plugin in the same project, ensure that both versions use the same addon interface version.

There are two ways to install the NativeCamera plugin into your project:

• Through the Godot Editor AssetLib
• Manually by downloading archives from GitHub

Installing via AssetLib

Steps:

• Search for NativeCamera in the Godot Editor AssetLib
• Click Download
• In the installation dialog:
  • Keep Change Install Folder set to your project root
  • Keep Ignore asset root checked
  • Click Install
• Enable the plugin from Project → Project Settings → Plugins

When installing both platforms via AssetLib, Godot may warn that some files conflict and will not be installed. This is expected and safe to ignore, as both platforms share the same addon interface code.

Installing manually

Steps:

• Download the release archive from GitHub
• Unzip the archive
• Copy the contents into your Godot project root
• Enable the plugin via Project → Project Settings → Plugins

Usage

Add a NativeCamera node to your main scene or register it as an autoload (singleton).

Typical workflow:

1. Query available cameras using get_cameras()
2. Choose a camera and desired output size
3. Create a FeedRequest to configure the stream
4. Start the camera feed
5. Receive frames via signals

Example

@onready var camera := $NativeCamera

func _ready():
    camera.camera_permission_granted.connect(_on_camera_permission_granted)
    camera.camera_permission_denied.connect(_on_camera_permission_denied)
    camera.frame_available.connect(_on_frame_available)
    camera.request_camera_permission()

func _on_camera_permission_granted() -> void:
    var cameras := camera.get_all_cameras()
    if cameras.is_empty():
        return

    var cam: CameraInfo = cameras[0]
    var request := FeedRequest.new()
        .set_camera_id(cam.get_camera_id())
        .set_width(1280)
        .set_height(720)
        .set_rotation(90)
        .set_grayscale(false)
        .set_mirror_horizontal(true)   # flip left-right (e.g. selfie camera preview)
        .set_mirror_vertical(false)
        .set_scale_width(640)          # downscale to 640×360 before emitting
        .set_scale_height(360)

    camera.start(request)

func _on_camera_permission_denied() -> void:
    push_error("Camera permission denied")

func _on_frame_available(frame: FrameInfo) -> void:
    var img := frame.get_image()
    # Use the image or raw buffer here

Example with auto-upright

When auto_upright is enabled the plugin detects device orientation in real time and automatically applies the correct rotation to every frame. There is no need to set rotation manually or track orientation changes in your code.

@onready var camera := $NativeCamera

func _ready():
    camera.camera_permission_granted.connect(_on_camera_permission_granted)
    camera.frame_available.connect(_on_frame_available)
    camera.request_camera_permission()

func _on_camera_permission_granted() -> void:
    var cameras := camera.get_all_cameras()
    if cameras.is_empty():
        return

    var cam: CameraInfo = cameras[0]
    var request := FeedRequest.new()
        .set_camera_id(cam.get_camera_id())
        .set_width(1280)
        .set_height(720)
        .set_auto_upright(true)        # rotate frames automatically — no manual rotation needed

    camera.start(request)

func _on_frame_available(frame: FrameInfo) -> void:
    var img := frame.get_image()
    # img is always upright regardless of how the device is held
    # frame.get_rotation() reports the rotation that was applied

You can also set auto_upright through the Inspector by enabling the Auto Upright export property on the NativeCamera node and then calling create_feed_request():

# In the Inspector, enable "Auto Upright" on the NativeCamera node, then:
var request := camera.create_feed_request()
camera.start(request)

Signals

Register listeners on the NativeCamera node:

• camera_permission_granted()
  • Emitted when camera permission is granted by the user
• camera_permission_denied()
  • Emitted when camera permission is denied by the user
• frame_available(frame: FrameInfo)
  • Emitted when a new camera frame is available

Methods

• has_camera_permission() -> bool
  • Returns whether camera permission has already been granted
• request_camera_permission()
  • Requests camera permission from the OS
• get_all_cameras() -> Array[CameraInfo]
  • Returns a list of available cameras
• create_feed_request() -> FeedRequest
  • Creates a FeedRequest pre-populated with the node's exported property values (frame_width, frame_height, frames_to_skip, frame_rotation, is_grayscale, mirror_horizontal, mirror_vertical, scale_width, scale_height, auto_upright)
• start(request: FeedRequest)
  • Starts the camera feed with the given configuration
• stop()
  • Stops the active camera feed

Classes

This section documents the GDScript interface classes implemented and exposed by the plugin.

CameraInfo

Encapsulates camera metadata provided by the mobile OS.

Properties / Methods:

• get_camera_id() -> String
• is_front_facing() -> bool
• get_output_sizes() -> Array[FrameSize]
• get_sensor_orientation() -> int
  • Returns the clockwise angle in degrees (0, 90, 180, or 270) that the camera sensor image must be rotated to be upright when the device is held in its natural (portrait) orientation. This value is a fixed hardware property of the camera and does not change with device rotation. Defaults to 0 when the value is unavailable (e.g. on emulators). Useful when implementing custom frame processing that needs to account for sensor mounting angle independently of device orientation.

FeedRequest

Defines configuration parameters for starting a camera feed.

Configurable options:

• Camera ID
• Output width and height
• Frames to skip (performance tuning)
• Rotation (degrees: 0, 90, 180, 270 — applied first; ignored when auto_upright is enabled)
• Grayscale capture
• Horizontal mirror (mirror_horizontal) — flips the frame left-to-right after rotation
• Vertical mirror (mirror_vertical) — flips the frame top-to-bottom after rotation
• Scale width and height (scale_width, scale_height) — resizes the pixel buffer to the given dimensions as the final post-processing step (after rotation and mirroring); both must be non-zero for scaling to take effect; defaults to 0 (disabled)
• Auto-upright (auto_upright) — when enabled, the plugin detects the current device orientation on every frame and automatically computes and applies the rotation needed to keep the image upright; the manual rotation value is ignored while this flag is active; defaults to false

Both mirror flags default to false and can be combined independently with any rotation value. Mirroring is applied as a post-processing step after rotation on both Android and iOS, so the axis labels always refer to the final upright image.

Scaling is applied after mirroring and uses nearest-neighbour interpolation, making it suitable for real-time use cases such as downscaling before CV inference. Setting either scale_width or scale_height to 0 disables scaling entirely.

When auto_upright is active, FrameInfo.get_rotation() reports the rotation that was actually applied to that frame, which changes dynamically as the device is tilted. This value can be used for diagnostics or to inform downstream processing.

Supports fluent chaining via setter methods.

Setter methods:

• set_camera_id(value: String) -> FeedRequest
• set_width(value: int) -> FeedRequest
• set_height(value: int) -> FeedRequest
• set_frames_to_skip(value: int) -> FeedRequest
• set_rotation(value: int) -> FeedRequest
• set_grayscale(value: bool) -> FeedRequest
• set_mirror_horizontal(value: bool) -> FeedRequest
• set_mirror_vertical(value: bool) -> FeedRequest
• set_scale_width(value: int) -> FeedRequest
• set_scale_height(value: int) -> FeedRequest
• set_auto_upright(value: bool) -> FeedRequest

FrameInfo

Represents a single captured frame.

Accessors:

• get_buffer() -> PackedByteArray
• get_width() -> int
• get_height() -> int
• get_rotation() -> int
• is_grayscale() -> bool
• get_image() -> Image

FrameSize

Represents a supported camera output resolution.

Accessors:

• get_width() -> int
• get_height() -> int
• get_raw_data() -> Dictionary

Platform-Specific Notes

Android

• Ensure Android export templates are installed
• Enable Gradle build in export settings
• Camera permission is required at runtime
• The "Two-Strike" Rule: Starting in Android 11, if a user taps "Deny" for a specific permission more than once during the app's lifetime on the device, the system will no longer show the dialog for future requests. Once this two-strike threshold is reached, any subsequent calls to request the permission will immediately be denied without showing any dialogs.

Auto-upright on Android:

When auto_upright is enabled the plugin reads the camera's SENSOR_ORIENTATION value (0, 90, 180, or 270°) from CameraCharacteristics once when the camera opens, and reads the live device rotation from Display.getRotation() on every processed frame. The required rotation is computed using the standard Camera2 formula:

Front cameras use addition rather than subtraction because their sensor image is horizontally mirrored, so the sensor and device rotations reinforce each other.

Troubleshooting:

• Logs (Linux/macOS): adb logcat | grep godot
• Logs (Windows): adb.exe logcat | select-string "godot"

Helpful resources:

• Godot Android export documentation
• Android Studio & ADB documentation

iOS

• Follow Godot's iOS export instructions
• Camera permission must be declared in the generated Xcode project
• Use Xcode console logs for debugging

Auto-upright on iOS:

When auto_upright is enabled the plugin subscribes to UIDevice.orientationDidChangeNotification (started and stopped alongside the camera session) and caches the most recently observed UIDeviceOrientation. On every processed frame it maps that orientation to the rotation degrees needed to make the raw sensor buffer upright:

Front and back cameras produce mirrored values in the landscape cases because the front sensor image is horizontally flipped relative to the back sensor. Portrait orientations are the same for both camera types because the mirror axis does not interact with a 90°/270° rotation.

All Plugins

✦	Plugin	Android	iOS	Stars
	Admob	✅	✅
	Connection State	✅	✅
	Deeplink	✅	✅
	Firebase	✅	✅
	In-App Review	✅	✅
	Native Camera	✅	✅
	Notification Scheduler	✅	✅
	OAuth 2.0	✅	✅
	QR	✅	✅
	Share	✅	✅
	Vision	✅	✅