Godot Vision Plugin

A Godot plugin that provides a unified GDScript interface for ML Kit face mesh detection on Android and iOS. Pass any Image to the Vision node and receive rich per-face data including 468 3-D landmark points, triangle mesh indices, and named facial contours — all in a single async call.

Key Features:

• Detect one or more faces in any Image using ML Kit's Face Mesh API
• Receive 468 normalised 3-D landmark points per face (x/y ∈ [0, 1], z = relative depth)
• Access the full triangle mesh (indices into the landmark array) for each detected face
• Query individual named contours — face oval, eyes, eyebrows, lips, and nose bridge — via FaceMeshInfo constants
• Built-in wireframe drawing utilities: overlay a mesh on an existing image or generate a transparent mesh layer for compositing
• Typed result and error classes (FaceScanResult, FaceMeshInfo, ScanError) for clean, idiomatic GDScript

Table of Contents

• Installation
• Usage
• Signals
• Methods
• Classes
• Platform-Specific Notes
• Links
• All Plugins
• Credits
• Contributing

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, then make sure that both versions use the same addon interface version._

There are 2 ways to install the Vision plugin into your project:

• Through the Godot Editor's AssetLib
• Manually by downloading archives from Github

Installing via AssetLib

Steps:

• search for and select the Vision plugin in Godot Editor
• click Download button
• on the installation dialog...
  • keep Change Install Folder setting pointing to your project's root directory
  • keep Ignore asset root checkbox checked
  • click Install button
• enable the plugin via the Plugins tab of Project->Project Settings... menu, in the Godot Editor

When installing via AssetLib, the installer may display a warning that states "_[x number of]_ files conflict with your project and won't be installed." You can ignore this warning since both versions use the same addon code.

Installing manually

Steps:

• download release archive from Github
• unzip the release archive
• copy to your Godot project's root directory
• enable the plugin via the Plugins tab of Project->Project Settings... menu, in the Godot Editor

Usage

Add a Vision node to your main scene or an autoload global scene.

• connect Vision node signals before calling scan_face()
  • face_mesh_ready(result: FaceScanResult) — emitted when detection succeeds
  • face_mesh_failed(error: ScanError) — emitted when detection fails
• call vision.scan_face(image) with any Image; the image is automatically converted to FORMAT_RGBA8 if needed
• in the face_mesh_ready callback, iterate over result.get_faces() to access per-face landmark data
• optionally use the static drawing helpers to render the mesh directly onto an image

Basic face scan example:

@onready var vision := $Vision

func _ready() -> void:
    vision.face_mesh_ready.connect(_on_face_mesh_ready)
    vision.face_mesh_failed.connect(_on_face_mesh_failed)

func scan(image: Image) -> void:
    vision.scan_face(image)

func _on_face_mesh_ready(result: FaceScanResult) -> void:
    print("Detected %d face(s)" % result.get_face_count())
    for face in result.get_faces():
        print("  Points: %d, Triangles: %d" % [face.get_points().size(), face.get_triangles().size()])

func _on_face_mesh_failed(error: ScanError) -> void:
    print("Scan failed [%s]: %s" % [error.get_code(), error.get_description()])

Drawing the mesh overlay onto an image:

func _on_face_mesh_ready(result: FaceScanResult) -> void:
    # Returns a new Image with the wireframe painted on top
    var annotated: Image = Vision.draw_face_mesh_on_image(original_image, result, Color.CYAN)
    $TextureRect.texture = ImageTexture.create_from_image(annotated)

Generating a transparent mesh layer for compositing:

func _on_face_mesh_ready(result: FaceScanResult) -> void:
    var mesh_layer: Image = Vision.generate_face_mesh_image(
        result, original_image.get_width(), original_image.get_height(), Color.LIME)
    $MeshOverlay.texture = ImageTexture.create_from_image(mesh_layer)

Accessing individual contours:

func _on_face_mesh_ready(result: FaceScanResult) -> void:
    var face: FaceMeshInfo = result.get_face(0)
    if face:
        var oval: Array = face.get_contour(FaceMeshInfo.CONTOUR_FACE_OVAL)
        for point in oval:
            print("Oval point: ", point)  # Vector3 — x/y normalised, z = depth

Signals

Register listeners to the following signals of the Vision node:

Methods

Vision node methods

Static drawing utilities

These are pure-GDScript helpers that operate on a FaceScanResult returned by the face_mesh_ready signal. They require no scene nodes or rendering server calls.

Classes

FaceScanResult

Encapsulates the full result of a scan_face() call. Received via the face_mesh_ready signal.

FaceMeshInfo

Encapsulates the mesh data for a single detected face.

Contour name constants (pass to get_contour()):

ScanError

Encapsulates error information delivered via the face_mesh_failed signal.

ScanError.Code enum values:

ImageInfo

Wraps a Godot Image as a serialisable dictionary for transfer to the native plugin. Used internally by scan_face() — you do not normally need to use this class directly.

Platform-Specific Notes

Android

• Download Android export template and enable gradle build from export settings
• Troubleshooting:
• Logs: adb logcat | grep 'godot' (Linux), adb.exe logcat | select-string "godot" (Windows)
• You may find the following resources helpful:
  • https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_android.html
  • https://developer.android.com/tools/adb
  • https://developer.android.com/studio/debug
  • https://developer.android.com/courses

iOS

• Follow instructions on Exporting for iOS
• View XCode logs while running the game for troubleshooting.
• See Godot iOS Export Troubleshooting.

Links

• AssetLib Entry Android
• AssetLib Entry iOS