# FIELD × JavaScript — Agent Guide (p5.js & vanilla web) > **Audience:** an AI coding agent asked to build an interactive p5.js sketch or a > vanilla-JS web page that reacts to FIELD in real time. This document is the > complete input/output contract. Follow it literally. --- ## 1. What FIELD gives you FIELD is a local visual canvas. Physical sensors (a phone, BLE, serial, OSC, MIDI) send data into FIELD; the user wires that data through rule-based **Cues** to named **outputs**. FIELD then broadcasts the resulting values over a **local WebSocket** so any web page can read them. Your job as a JS author is only to **read numbers and draw**. You never open a raw WebSocket yourself — you include one small library, `field-bridge.js`, and call its `field.*` API. **Every value is a number from 0 to 1.** - **Raw sensor value:** `field.sensor('TILT')` → the phone tilt, 0–1, straight from the device. - **Cue output value:** `field.get('MOVE')` → the value *after* the user's Mechanism (SWITCH / DIAL / LATCH / etc.) has transformed it. Prefer this when the user has drawn a Cue; it respects their logic. --- ## 2. Include the library `field-bridge.js` ships next to this file. Load it before your sketch. The library infers the FIELD WebSocket URL from its own `src`, so **point the `src` at the running FIELD app** (the desktop app serves it on `localhost` — default port 5173 in dev, or whatever the app prints). ```html ``` If you host the page elsewhere and only have a copy of the library, set the URL explicitly **before** the script tag: ```html ``` There is no build step, no npm install, no bundler. Plain ` ``` Key points for the agent: - Map 0–1 to whatever visual range you need (`* width`, `* 360` for degrees, etc.). - Clamp only if you compute derived values; FIELD values are already 0–1. - Use `field.actor(name).get(...)` when the project has several Actors with the same output atom and you must tell them apart. --- ## 5. Vanilla JS pattern (no p5) Use `field.on()` to push values into the DOM, or poll with `requestAnimationFrame`. Event-driven is cleaner for DOM. ```html

``` `field.on(cb)` returns an unsubscribe function — call it on teardown if you build a single-page app that mounts/unmounts. --- ## 6. Multi-instance sensors (advanced) One Actor can carry several atoms of the same type (e.g. a 12-pad touch board). FIELD keys them by suffix: - 1st `TOUCH` → `'TOUCH'` - 2nd → `'TOUCH_1'` - 3rd → `'TOUCH_2'` … nth → `'TOUCH_{n-1}'` Read them the same way: `field.sensor('TOUCH_3')`. Cue outputs are read by their output atom name (and optionally scoped by actor), not by a suffix. --- ## 7. Under the hood (only if you must open the socket yourself) You normally do **not** need this — use `field-bridge.js`. But the wire protocol is: - **URL:** `ws://localhost:5173/ws` (or `wss://` when FIELD serves HTTPS). - **On connect, send:** `{ "type": "hello", "clientType": "sketch" }`. `clientType: "sketch"` receives *both* sensor events and output snapshots. - **You then receive** JSON messages: ```jsonc // raw sensor, one per device event { "type": "sensor_event", "atom": "TILT", "value": 0.62, "actorId": "…", "raw": { "alpha": 12, "beta": 4, "gamma": 21 } } // post-mechanism outputs, broadcast whenever the canvas recomputes { "type": "output_snapshot", "projectName": "…", "sceneName": "Intro", "sceneId": "…", "states": [ { "atom": "MOVE", "value": 0.8, "actorId": "…", "actorName": "Robot" } ] } ``` `sensor_event.atom` is a **string** (supports multi-instance keys like `"TOUCH_3"`), not an enum. Values are always numbers 0–1. --- ## 8. Do / Don't for the agent **Do** - Read with `field.get()` / `field.sensor()`; default missing values with `?? 0`. - Treat every value as 0–1 and map it into your own visual range. - Prefer Cue outputs (`field.get`) over raw sensors when a Cue likely exists. - Show a small connected/waiting indicator; sensors may not be live yet. **Don't** - Don't invent new atom names — only the ones listed in §3 exist. - Don't expect values outside 0–1, and don't send unit conversions back. - Don't hardcode `localhost:5173` if the user says FIELD runs on another host — set `window.FIELD_WS_URL` instead. - Don't add a build step, framework, or bundler unless the user explicitly asks.