OpenParable
Skip to content
← Back to skills

Bindings Synchronization

Development
bindings-synchronization

Bindings Synchronization is an Agent Skill for development published in the google/filament repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guidelines and SOP for synchronizing public C++ API changes (methods, enums, options structs) to Java (Android JNI) and JavaScript/TypeScript (Web/WASM Embind).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/google/filament/blob/HEAD/skills/bindings_synchronization/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bindings-synchronization, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Cross-Platform Language Bindings Synchronization

When making changes to public Filament C++ APIs, AI agents must ensure the changes are mirrored in the Java and JavaScript/TypeScript binding layers.


1. Trigger Conditions

You must check and update the language bindings if your changes touch any public headers under filament/include/filament/, specifically:

  • New/Modified/Deleted Methods on core classes (e.g., View, Engine, Camera, LightManager, RenderableManager).
  • Options Structs (e.g., AmbientOcclusionOptions, BloomOptions, FogOptions).

    [!IMPORTANT] If you modify options structs defined in filament/include/filament/Options.h, you must run the beamsplitter tool. The tool parses Options.h and automatically updates Java bindings, JavaScript/TypeScript bindings, and C++ JSON serialization files.

    Run it via:

    cd tools/beamsplitter && go run .
    
  • Enums & Constants (e.g., BlendMode, QualityLevel, AntiAliasing under filament/include/filament/ or nested inside classes).

2. Java & Android JNI Synchronization

All JNI JNI-exported functions use automatic symbol resolution (dynamic mapping), meaning they are mapped by signature rather than a static registration table.

File Mappings

  • Java Class: android/filament-android/src/main/java/com/google/android/filament/<ClassName>.java
  • JNI C++ Wrapper: android/filament-android/src/main/cpp/<ClassName>.cpp

Guidelines

  1. API Consistency: Keep method visibility public (unless the API is strictly internal to the Java package). Follow Java naming conventions (camelCase).
  2. Getter/Setter Completeness: If you add a Setter (e.g., setFoo), always add the corresponding Getter (e.g., isFoo or getFoo).
  3. JNI Signature:
    • Native declarations in Java must be private static native.
    • The corresponding C++ function in JNI must be decorated with extern "C" JNIEXPORT <ReturnType> JNICALL Java_com_google_android_filament_<ClassName>_<NativeMethodName>.
    • Return values from native C++ booleans should be cast to jboolean using (jboolean) or static_cast<jboolean>().

3. JavaScript & TypeScript Synchronization

Filament uses Emscripten's Embind to export C++ APIs to JS.

File Mappings

  • Embind Source: web/filament-js/jsbindings.cpp
  • Enums Embind Source: web/filament-js/jsenums.cpp
  • TypeScript Definition: web/filament-js/filament.d.ts
  • JS Extension Wrappers: web/filament-js/extensions.js

Guidelines

  1. Embind Registration:
    • Register member functions in jsbindings.cpp within the corresponding class_<ClassName>("<JSClassName>") block using .function("methodName", &ClassName::methodName).
  2. TypeScript Declarations:
    • Always update filament.d.ts to match any changes. Every bound C++ method should have a corresponding declaration inside export class <ClassName> to avoid IDE type errors.
  3. Complex Option Structs:
    • If you modify or add fields to an options struct (like BloomOptions), make sure to:
      • Register the new fields in jsbindings.cpp using .field("fieldName", &ClassName::Options::fieldName).
      • Update the TypeScript interface in filament.d.ts to include the new properties.
      • Check if extensions.js contains a prototype-overrides wrapper for merging the options (e.g., Filament.View.prototype.setBloomOptions). Update the default options object if needed.

4. Verification Check

Before concluding a task:

  1. Double-check JNI signature signatures against the Java class.
  2. Verify that type bindings and return types match up.
  3. Verify that TS definitions in filament.d.ts are 100% synchronized.