Skip to main content

Troubleshooting Guide

Common issues and solutions for the SOAP Binding System.

Binding Not Updating​

Symptoms: UI not reflecting Variable changes

Diagnostics​

  1. Check Binding Status

    • Inspector shows ✅ Valid?
    • If ❌ Error, read error message

  2. Verify Configuration

    - SOAP asset assigned?
    - Target component assigned?
    - Property name correct?
    - Auto-update enabled?

  3. Enable Logging

    Advanced Settings:
    ☑ Log Bind Events = true

    // Check Console for:
    "[SOAPBind] Binding updated: health → fillAmount (value: 0.75)"

  4. Check Binding Mode

    // InitialSync updates once only
    Mode: InitialSync → Check if already executed

    // Should be VariableToTarget for continuous updates
    Mode: VariableToTarget ✅

Common Causes​

CauseSolution
Binding mode = InitialSyncChange to VariableToTarget
Component destroyedRe-assign target component
Variable not changingVerify Variable.SetValue() is called
Auto-update disabledEnable in Advanced Settings
Update interval too highReduce interval (0 = event-driven)

Type Compatibility Errors​

Symptoms: Binding shows ❌ error status

Common Mismatches​

SourceTargetIssueSolution
FloatVariableTextMeshPro.textType incompatibleEnable String Formatting: "{0:F2}"
IntVariableImage.fillAmountRange mismatchEnable Transformation: Input (0,100) → Output (0,1)
BoolVariableSlider.valueType incompatibleUse FloatVariable or IntVariable instead
StringVariableTransform.positionCompletely incompatibleWrong target - choose string property

Type Validation Checklist​

✓ Float → float property     (direct)
✓ Float → string property    (with String Format)
✓ Int → int property         (direct)
✓ Int → float property       (with Transformation)
✓ Bool → bool property       (direct)
✓ Vector3 → Vector3 property (direct)
✗ Bool → float property      (use Float/IntVariable)
✗ String → numeric property  (incompatible)

Transformation Not Working​

Symptoms: Values not transformed as expected

Diagnostics​

  1. Verify Transformation Enabled

    ☑ Use Transformation = true

  2. Check Input Range

    // Input range must cover actual Variable values
    Variable value: 75
    Input Range: (0, 100) ✅
    Input Range: (0, 50)  ❌ Value out of range!

  3. Inspect Curve

    // Click curve field in Inspector
    // Verify curve shape is correct
    // Check keyframe positions

  4. Verify Output Range

    // Ensure output range matches target property
    Target: Image.fillAmount (expects 0-1)
    Output Range: (0, 1) ✅
    Output Range: (0, 100) ❌ Will exceed valid range!

Transformation Limitations​

Unsupported Types:

❌ BoolVariable   → Cannot use numeric transformation
❌ StringVariable → Cannot use numeric transformation
❌ GameObject     → Cannot use numeric transformation

// Solution: Use appropriate transformation type
BoolVariable → Use Boolean Invert instead
StringVariable → Use String Formatting instead

Performance Issues​

Symptoms: Frame rate drops with active bindings

Diagnostics​

  1. Open Bind Manager

    Window > SoapKit > Bind Manager > Performance Tab

  2. Identify Bottlenecks

    // Sort by "Cost" column
    // Look for red indicators (>5ms)
    // Check "Optimization Potential" section

  3. Check Inspector Metrics

    ☑ Show Performance Metrics
    // Look for orange/red bars

Solutions​

High Execution Time:

// Problem: Binding costs >2ms
updateInterval = 0.0f  // Every frame

// Solution: Increase interval
updateInterval = 0.1f  // 10 FPS - often sufficient

Too Many TwoWaySync Bindings:

// Problem: Non-interactive UI using TwoWaySync
Mode: TwoWaySync  // Higher overhead

// Solution: Change to one-way
Mode: VariableToTarget  // Lower overhead

Complex Transformations:

// Problem: Curve with 20+ keyframes
transformationCurve = ComplexCurve(20 keyframes)

// Solution: Simplify to 3-5 keyframes
transformationCurve = SimpleCurve(3 keyframes)

String Formatting on High-Frequency Updates:

// Problem: FPS counter updating 60 times/sec
stringFormat = "FPS: {0:F2}"
updateInterval = 0.0f

// Solution: Reduce update frequency
updateInterval = 0.5f  // Update every 0.5 seconds

Event Binding Not Firing​

Symptoms: EventToMethod binding doesn't execute

Diagnostics​

  1. Verify Event Asset

    // Is the correct GameEvent assigned?
    Asset: OnPlayerDied (UnitGameEvent) ✅

  2. Check Method Signature

    // Method must match event type
    UnitGameEvent → void Method()           ✅
    IntGameEvent  → void Method(int value)  ✅
    BoolGameEvent → void Method()           ❌ Missing parameter

  3. Confirm Event is Raised

    // Add logging to game code
    void Die() {
        Debug.Log("Raising OnPlayerDied");
        onPlayerDied.Raise();
    }

  4. Enable Binding Logs

    ☑ Log Bind Events = true
    // Should see: "[SOAPBind] Event raised: OnPlayerDied → Play()"

Common Causes​

CauseSolution
Wrong event asset assignedRe-assign correct event
Method signature mismatchFix parameter types
Event never raisedCheck game logic
Component destroyedRe-create binding

Null Reference Errors​

Symptoms: Console errors about null references

Common Errors​

Missing SOAP Asset:

NullReferenceException: soapAsset is null

// Solution:
// 1. Select SOAPBind component
// 2. Find binding with missing asset (shown as ❌)
// 3. Drag SOAP asset to assignment field

Destroyed Component:

MissingReferenceException: targetComponent has been destroyed

// Solution:
// 1. Remove or re-assign binding
// 2. Or delete GameObject with SOAPBind if no longer needed

Missing Property:

MemberAccessException: Property 'fillAmount' not found

// Solution:
// 1. Verify component type is correct (e.g., Image not Text)
// 2. Check property name spelling
// 3. Refresh component list (click property dropdown again)

TwoWaySync Issues​

Symptoms: Infinite loops or unexpected behavior

Loop Prevention​

SOAPBind includes automatic loop detection:

// Built-in safety:
// 1. Tracks last updated value
// 2. Skips update if value unchanged
// 3. Prevents circular updates

// But you should still avoid:
Variable A ↔ Component X ↔ Variable B ↔ Component Y ↔ Variable A

Debugging TwoWaySync​

  1. Enable Logging

    ☑ Log Bind Events = true
    // Watch for repeated updates

  2. Check for Loops

    Window > SoapKit > Bind Manager > Validation Tab
    // Warns about potential circular dependencies

  3. Simplify Bindings

    // If problematic, change to one-way
    TwoWaySync → VariableToTarget or TargetToVariable

Inspector Issues​

Symptoms: Binding configuration not working properly

Component Not Showing in Dropdown​

Cause: Component not on selected GameObject or children

Solution:

// 1. Verify component exists
GetComponent<Image>() != null

// 2. Refresh component list
// Click component dropdown → List refreshes

// 3. Check if component is on child
// Use GameObject mode or target child directly

Property List Empty​

Cause: No compatible properties for selected component

Solution:

// 1. Check if component has public properties
// Example: SpriteRenderer has 'color' but not 'fillAmount'

// 2. Try different binding type
Type: UI → Type: Property

// 3. Verify component type is correct
// TextMeshProUGUI ≠ Text (legacy)

Validation Warnings​

Symptoms: ⚠️ warnings in Bind Manager Validation Tab

Common Warnings​

Default String Format:

⚠️ Using default string format "{0}"

// Not an error, but can be removed:
☐ Use String Format = false

TwoWaySync with High Frequency:

⚠️ TwoWaySync with updateInterval = 0 (high overhead)

// Consider one-way if UI is read-only:
Mode: VariableToTarget

Unnecessary Linear Transformation:

⚠️ Transformation enabled but curve is linear

// Can be replaced with simple input/output range:
☐ Use Transformation = false
// Just adjust Variable value directly

Debug Workflow​

Step-by-Step Debugging​

  1. Visual Inspection

    Inspector: Check ✅/❌/⚠️ status

  2. Enable Logging

    ☑ Log Bind Events = true

  3. Test Manually

    Click [▶️] button next to binding

  4. Check Bind Manager

    Window > SoapKit > Bind Manager > Debugger Tab

  5. Validate All

    Right-click SOAPBind → Validate All Bindings

Getting Help​

If issues persist:

  1. Export Validation Report

    Bind Manager > Validation Tab > Export Report

  2. Check Documentation

  3. Common Patterns

Next Steps​