WIRESYNDICATEDocumentation

Dynamic Textures (Godot)

The WireSyndicate Godot SDK relies on asynchronous texture streaming to ensure the main rendering thread is never blocked during high-resolution ad payload delivery. This is achieved using Godot's WorkerThreadPool.

1. The WSPlacementNode

The core building block of spatial delivery in Godot is the WSPlacementNode (ws_placement_node.gd).

  1. Attach the ws_placement_node.gd script to a Node3D in your scene.
  2. In the Inspector, specify the Target Mesh Path to a valid MeshInstance3D in your hierarchy.
  3. Specify the Surface Index (integer) where the ad material will be applied (default is 0).
  4. Enter your exact Placement ID.

At runtime, WSPlacementNode fetches the programmatic creative payload and offloads the byte decoding to the background thread pool. Once decoded, it overrides the MeshInstance3D's material on the designated surface with the new dynamic texture.

2. Telemetry and Bids (v1.5.0)

When the asynchronous delivery finishes, the node caches the winning bid's ID internally as active_bid_id. This ID is mathematically required to clear the payment on the ledger.

You are responsible for emitting telemetry only when the mesh is verifiably visible to the camera (e.g., via a VisibleOnScreenNotifier3D and occlusion raycasts).

# Generate a standard UUID v4 for the zero-trust impression token
var impression_token = generate_uuid_v4()
 
# Dispatch securely via the WireSyndicate singleton
WireSyndicate.dispatch_impression(
    impression_token,
    ws_node.placement_id,
    ws_node.active_bid_id,
    dwell_time_seconds,
    screen_coverage_percentage
)

3. Best Practices

  • Occlusion Culling: Do not emit telemetry if the mesh is blocked by other geometry or particles.
  • Web Export (HTML5): The Godot SDK relies entirely on native Godot engine classes (HTTPRequest, HMACContext). Therefore, HTML5 exports are fully supported without native C++ dependencies. When testing web builds locally, ensure your dev server handles CORS headers appropriately.