bevy_agent_feedback_plugin/lib.rs
1//! Agent-friendly input, timing, diagnostics, and screenshot control for Bevy apps.
2//!
3//! `bevy-agent-feedback-plugin` exposes a bounded local protocol for input,
4//! semantic game readiness, deterministic Bevy time, and completion-confirmed
5//! primary-window PNGs. Protocol readiness means only that the socket exists;
6//! animated games should wait on a registered predicate/target and then capture
7//! after one app update. Strict pixel stability is appropriate only for static
8//! content or a bounded static region.
9//!
10//! # Quick start
11//!
12//! Add feedback after [`DefaultPlugins`] (or after the plugins that provide
13//! Bevy time, window, render, and input resources):
14//!
15//! ```no_run
16//! use bevy::prelude::*;
17//! use bevy_agent_feedback_plugin::{AgentFeedbackConfig, AgentFeedbackPlugin};
18//! use std::{net::SocketAddr, path::PathBuf};
19//!
20//! App::new()
21//! .add_plugins(DefaultPlugins)
22//! .add_plugins(AgentFeedbackPlugin::new(AgentFeedbackConfig {
23//! bind_addr: SocketAddr::from(([127, 0, 0, 1], 0)),
24//! protocol_file: PathBuf::from("target/agent-feedback/agent-feedback.json"),
25//! capture_dir: PathBuf::from("target/agent-feedback/captures"),
26//! deterministic_time: true,
27//! ..Default::default()
28//! }))
29//! .run();
30//! ```
31//!
32//! The generated protocol file is authoritative for the 0.5 socket, heartbeat,
33//! commands, deterministic-time mode, and caps. The wire envelope remains
34//! `{"id":...,"command":...}` with responses containing `ok` and either
35//! `result` or `error`.
36//!
37//! # Timing, capture, and diagnostics
38//!
39//! Public clients call `wait_frames` for app-update progress; the compatibility
40//! wire command remains `"wait"`. App updates are neither elapsed gameplay time
41//! nor compositor-presented frames. `wait_seconds` observes normal Bevy virtual
42//! time and is rejected while deterministic time is frozen. `advance_time`
43//! progresses deterministic Bevy virtual/fixed time in bounded nominal steps.
44//! Deterministic mode does not control direct [`std::time::Instant`], OS/network
45//! clocks, unseeded RNG, or other external state.
46//!
47//! `capture_after_frames` and `wait_until_first_capture` return metadata for
48//! screenshot readback: sequence/path/label, request/completion app-update
49//! frames, physical image dimensions, request/completion window state, and
50//! `screenshot_captured` completion. Readback and PNG persistence do not prove
51//! that the OS/window compositor presented the image.
52//!
53//! With the `diagnostics` feature, `AgentFeedbackDiagnosticsPlugin` explicitly
54//! registers states, scalar resource fields, and marker components for
55//! predicates and semantic targets. Exact duplicate Name/accessibility/marker
56//! targets error rather than choosing the first. Input/target coordinates are
57//! logical window pixels; PNG masks and crop regions are physical image pixels.
58//!
59//! # Scheduling and limits
60//!
61//! Agent commands enter in `PreUpdate` before Bevy input consumers. Screenshot
62//! responses complete only after Bevy render readback. Queues, request lines,
63//! waits, actions, time advances, diagnostics scans, captures, and response time
64//! are bounded by [`AgentFeedbackConfig`] and advertised in the protocol file.
65//! Keep the localhost bind unless the socket is protected from untrusted clients.
66//!
67//! # Canonical workflow
68//!
69//! See [`skills/driving-bevy-games/SKILL.md`](https://github.com/njfio/bevy-agent-feedback-plugin/blob/main/skills/driving-bevy-games/SKILL.md)
70//! for setup, readiness selection, semantic waits, input defaults, visual
71//! fallbacks, and artifact handling. See `examples/agent_driven.rs` for the
72//! self-driving Rust client.
73
74#![warn(missing_docs, rustdoc::broken_intra_doc_links)]
75
76pub mod client;
77mod config;
78mod control;
79#[cfg(feature = "diagnostics")]
80mod diagnostics;
81mod key_names;
82mod protocol;
83mod runtime;
84mod session;
85
86use bevy::prelude::*;
87pub use config::AgentFeedbackConfig;
88use control::AgentFeedbackControlPlugin;
89#[cfg(feature = "diagnostics")]
90pub use diagnostics::AgentFeedbackDiagnosticsPlugin;
91pub use protocol::DiagnosticValue;
92#[cfg(feature = "diagnostics")]
93pub(crate) use protocol::{
94 ComparisonOperator, ObservedPredicate, Predicate, PredicateOutcome, TargetKind, TargetSelector,
95};
96use runtime::AgentFeedbackRuntimePlugin;
97
98/// Bevy plugin that exposes local agent input and screenshot control.
99///
100/// Add this after [`bevy::time::TimePlugin`] and the plugins that create input,
101/// window, and render resources. [`DefaultPlugins`] is the usual choice.
102/// Deterministic time requires those time resources to exist before this plugin.
103/// Add `AgentFeedbackDiagnosticsPlugin` separately for registered semantic
104/// diagnostics when the `diagnostics` feature is enabled.
105#[derive(Default)]
106pub struct AgentFeedbackPlugin {
107 config: AgentFeedbackConfig,
108}
109
110impl AgentFeedbackPlugin {
111 /// Creates the plugin with explicit runtime configuration.
112 pub fn new(config: AgentFeedbackConfig) -> Self {
113 Self { config }
114 }
115}
116
117impl Plugin for AgentFeedbackPlugin {
118 fn build(&self, app: &mut App) {
119 app.insert_resource(self.config.clone())
120 .add_plugins((AgentFeedbackRuntimePlugin, AgentFeedbackControlPlugin));
121 }
122}