Srib integration

srib-integration

Project: SRIB — Godot 4.6 Android application with a 3D SmartThings home view. Role: Integration layer. Connects what srib-view draws with what srib-model computes, and bridges Godot to the Android platform.

---

Scope

Integration concerns in this project:

Area	What it covers
Scene wiring	Composing view nodes + model nodes into working scenes; signal connections; @onready paths
Autoload singletons	Global state managers (device state, SmartThings data cache, app config)
SmartThings bridge	Reading SmartThings device status into Godot; mapping device state → visual/model parameters
Android plugin/JNI	GDExtension .gdextension + .aar plugin setup; calling Java/Kotlin from GDScript
Export pipeline	export_presets.cfg configuration; Gradle build; APK signing; on-device deployment
Scene composition	Instantiating sub-scenes, setting up cameras, viewports, and the home 3D layout
Signal routing	Defining and connecting signals between model (data ready) and view (update visual)

---

Invocation

srib-integration SRIB-NNN

Where SRIB-NNN is a ticket from issues/SRIB-NNN.md. Read the ticket first — it defines scope, acceptance criteria, and which view/model tickets this integrates.

---

Workflow

Step 1 — Read the ticket

Read issues/SRIB-NNN.md. Extract:

• What view output (shader param, material, node state) needs to be driven
• What model output (computed value, animation state, data structure) is the source
• What Android/SmartThings data feeds in

If the dependent view or model tickets are not yet merged, stop and tell the user: "This integration ticket depends on SRIB-X (view) and SRIB-Y (model). Merge those first."

Step 2 — Locate the relevant files

Search the project for:

• The scene file (.tscn) that composes the relevant nodes
• The GDScript (.gd) files for both the view node and model node
• Any existing autoload in project.godot under [autoload]
• The Android plugin directory (android/plugins/ or android/build/)

Use grep -r and find rather than guessing paths.

Step 3 — Wire signals and data flow

The standard SRIB data flow pattern:

SmartThings/Android data
        ↓
   Autoload singleton (DeviceState.gd)
        ↓  signal: device_updated(id, state)
   Model node (e.g., RoomModel.gd)
        ↓  signal: visual_params_ready(params: Dictionary)
   View node (e.g., RoomShaderController.gd)
        ↓  shader_material.set_shader_parameter(...)
   MeshInstance3D / shader

When wiring:

1. Signals go top-down; the model never imports the view.
2. View nodes receive a Dictionary of named params — they do not know where the data came from.
3. Autoloads are read-only by consumers; only one writer per data type.
4. Scene tree connections use connect() in _ready() or %NodeName unique-name syntax.

Step 4 — Android bridge (when needed)

If the ticket touches Android:

GDExtension plugin setup:

• Check android/plugins/ for existing .gdextension file
• Java/Kotlin plugin class must extend GodotPlugin
• Register methods with @UsedByGodot annotation
• Rebuild .aar with ./gradlew build before testing

Calling from GDScript:

var plugin = Engine.get_singleton("SmartThingsPlugin")
if plugin:
    plugin.connect("device_state_changed", _on_device_state_changed)
    plugin.request_device_status(device_id)

SmartThings flow:

1. Android plugin fetches device state via SmartThings REST API
2. Emits Godot signal with raw state dict
3. DeviceState autoload normalises and caches
4. Emits device_updated for model nodes to consume

Step 5 — Export / build (when needed)

For APK changes:

1. Verify export_presets.cfg has the correct custom_template/debug and custom_template/release paths
2. Confirm android/build/config.gradle lists all required permissions
3. Export from editor: Project → Export → Android → Export Project
4. Install on device: adb install -r <apk-path>
5. Check logcat: adb logcat -s Godot:V

---

Acceptance checklist

Every integration ticket must pass before closing:

• Signals connect without errors (_ready() runs with no "connect" errors in Output)
• Data flows from source to view: change a model value, verify the shader/visual updates
• No orphaned signals (every connect has a matching disconnect or autofreed owner)
• Tested in Godot editor (Play Scene, F5)
• Tested on Android device or emulator (APK installed, correct behavior observed)
• No regressions: other scenes still run without errors
• project.godot autoloads section is clean (no duplicate or dead entries)
• If Android plugin changed: .aar rebuilt and committed

---

Common pitfalls

• Circular signal dependencies — model signals view, view signals model. Break the cycle by routing through the autoload singleton.
• Shader param name mismatch — set_shader_parameter("param_name", v) silently does nothing if the name doesn't match the shader uniform. Always verify the exact uniform name in the .gdshader file.
• Plugin not found — Engine.get_singleton("X") returns null on desktop builds. Always null-check before calling plugin methods.
• Scene path fragility — avoid hardcoded $Node/Child/Grandchild paths; prefer %UniqueNodeName or @export var references.
• Export template mismatch — if the Godot version changes, export templates must be re-downloaded and re-set in the export preset.

---

File conventions

Type	Path pattern
Autoload singletons	scripts/autoloads/<Name>.gd
Android plugin	android/plugins/<name>/
Integration scripts	scripts/integration/<FeatureName>Integration.gd
Scene compositions	scenes/<room_or_feature_name>.tscn