FIELD has two written specs — AI-JS.md and AI-PLUGINS.md — meant to be read by an AI coding assistant (Claude, Cursor, Copilot, whatever you use), not a human. Handing one to your agent is often faster than reading the guide yourself.
This page is the front door to both. Read it first, watch one worked example — an ESP32 board and a p5.js sketch talking to each other through FIELD — then grab whichever spec matches what you're building.
The spec files are dense and literal on purpose — an agent wants a strict contract, not prose. That makes them a bad first read for a human. This page is the human-readable version: one real example, then the spec, in that order.
Both files describe a contract for an agent to follow literally. They cover opposite ends of FIELD: one is about the screen, the other is about the wire.
How a p5.js sketch or web page reads live FIELD values over field-bridge.js. No hardware involved.
How to write a .field-plugin.json file that teaches FIELD a new sensor chip on an Arduino/ESP32 board.
Most real projects use both: a board reading a sensor FIELD already knows (or a plugin you asked an agent to write), and a sketch drawing the result. That's exactly what the worked example in the next chapters builds.
One ESP32 board, one potentiometer, one browser tab. Turn the knob — a circle drawn in p5.js moves across the screen, live, over Wi-Fi.
The ESP32 talks to FIELD the normal way — generated Arduino code, wired over the same Wi-Fi as your computer (or plain USB serial). The sketch talks to FIELD over a local WebSocket via field-bridge.js. FIELD sits in the middle, applying whatever Cue and Mechanism you drew on the canvas — the two ends never talk to each other directly.
An ESP32 dev board, one potentiometer (or reuse your phone's tilt sensor instead — no board required to try the software half), and the FIELD desktop app running. Board and computer don't even need the same Wi-Fi if you flash over USB.
You don't hand-write any Arduino code for this — FIELD generates the whole sketch from the canvas.
.ino file — includes, setup, and a loop reading analogRead() and sending it to FIELD.Skip this chapter and give Knob a TILT role instead, connected via Connect → Phone. Everything in Chapters 4–5 works identically — FIELD doesn't care whether the number came from an ESP32 or a phone.
Add a second Actor — call it "Ball" — with a MOVE output role. Drag from Knob's SLIDER port to Ball's MOVE port. That line is the Cue; the pill on it is the Mechanism.
Leave the Mechanism as a plain DIAL — output tracks input directly, 0 to 1. Now turning the knob changes Ball's MOVE value, visible live in the Actor panel, with nothing written yet.
Swap the Mechanism to SWITCH with a threshold at 0.5 — the ball should now snap between two positions instead of sliding smoothly. This is the part an AI agent never sees or needs to know about: it only ever reads the number that comes out the other side.
This is the part AI-JS.md is written for — hand this exact file to your coding agent and ask for a sketch, or copy the pattern below by hand.
knob-ball.html
<!DOCTYPE html>
<html>
<head><meta charset="utf-8" /></head>
<body>
<script src="https://cdn.jsdelivr.net/npm/p5@1.9.4/lib/p5.min.js"></script>
<script src="./field-bridge.js"></script>
<script>
function setup() {
createCanvas(windowWidth, windowHeight);
noStroke();
}
function draw() {
background(13, 12, 10);
const move = field.get('MOVE') ?? 0.5; // Ball's Cue output, 0-1
const x = move * width; // 0-1 -> across the screen
fill(124, 58, 237);
circle(x, height / 2, 60);
fill(255); textSize(12); textFont('monospace');
text(field.connected ? 'FIELD ● live' : 'FIELD ○ waiting…', 16, 24);
}
function windowResized() { resizeCanvas(windowWidth, windowHeight); }
</script>
</body>
</html>Save it, open it in a browser while FIELD is running, and turn the knob — the violet circle tracks it in real time. No build step, no npm install: just the two <script> tags.
Once the ESP32 and the Cue exist (Chapters 3–4), the fastest way to get the p5.js half is to describe what you want and hand your agent the spec — not to write it yourself.
field-bridge.js.See an empty project — no scaffolding needed..field-plugin.json file, following the same rules as the plugin-writing guide.See a plugin file you install through Connect → Plugins, no code review needed.Both files are written as a strict contract, not a tutorial: exact role names, exact function signatures, an explicit Do/Don't list. That's deliberate — it's what keeps an agent from inventing role names or wire formats that don't exist in FIELD.
Download whichever matches what you're building, and paste it straight into your agent's chat.
Prefer to read the plugin format yourself first, step by step? See the human-readable plugin guide — it walks through the exact same spec with a worked example of its own.
An ESP32 sends a number, FIELD applies your Cue, a p5.js sketch draws it — and an AI agent can write either end for you once it has the right spec.
← Back to Your First FIELD · Add a custom sensor · FIELD home