Skip to main content

bevy_agent_feedback_plugin/
config.rs

1use bevy::prelude::Resource;
2use std::{net::SocketAddr, path::PathBuf, time::Duration};
3
4/// Runtime configuration for [`crate::AgentFeedbackPlugin`].
5///
6/// Defaults bind to localhost on port `15712`, write `agent-feedback.json`,
7/// keep captures in `agent-feedback-captures`, and refresh a heartbeat for protocol 0.5
8/// stale-session checks.
9#[derive(Clone, Debug, Resource)]
10pub struct AgentFeedbackConfig {
11    /// TCP address used by the local JSON-lines control socket.
12    ///
13    /// Use port `0` to let the operating system choose a free port. The chosen
14    /// address is written to [`protocol_file`](Self::protocol_file).
15    pub bind_addr: SocketAddr,
16
17    /// JSON file written at startup so Pi/Codex agents can discover the socket.
18    pub protocol_file: PathBuf,
19
20    /// Directory where `capture` commands write PNG screenshots.
21    pub capture_dir: PathBuf,
22
23    /// Maximum queued agent commands drained per frame.
24    pub max_pending_commands: usize,
25
26    /// Maximum accepted frame count for a single `wait` command.
27    pub max_wait_frames: u16,
28
29    /// Maximum accepted step count for compound actions such as `drag`.
30    pub max_action_steps: u16,
31
32    /// Freezes Bevy virtual time between explicit advancement commands.
33    ///
34    /// The default is `false`, which preserves Bevy's normal time behavior.
35    pub deterministic_time: bool,
36
37    /// Maximum number of deterministic deltas in one `advance_time` command.
38    ///
39    /// This cap is always treated as at least one by protocol discovery and
40    /// request validation. The default is `600`.
41    pub max_time_advance_steps: u16,
42
43    /// Maximum gameplay duration accepted by one `advance_time` command.
44    ///
45    /// The default is 10 seconds. Wire durations must also be finite, positive,
46    /// and nonzero after conversion to [`Duration`].
47    pub max_time_advance: Duration,
48
49    /// How often the plugin refreshes the session heartbeat file.
50    pub heartbeat_interval: Duration,
51
52    /// How old the heartbeat may be before clients reject the session as stale.
53    pub session_stale_after: Duration,
54
55    /// Maximum number of retained PNG captures.
56    ///
57    /// Older capture files created by this plugin are removed after this limit.
58    pub max_captures: usize,
59
60    /// Maximum time a socket client waits for the game to answer a command.
61    pub command_timeout: Duration,
62
63    /// Optional app exit after no accepted agent commands for this duration.
64    /// Values below 5 seconds are clamped up; `None` disables idle shutdown.
65    pub idle_shutdown_after: Option<Duration>,
66}
67
68impl Default for AgentFeedbackConfig {
69    fn default() -> Self {
70        Self {
71            bind_addr: SocketAddr::from(([127, 0, 0, 1], 15712)),
72            protocol_file: PathBuf::from("agent-feedback.json"),
73            capture_dir: PathBuf::from("agent-feedback-captures"),
74            max_pending_commands: 32,
75            max_wait_frames: 300,
76            max_action_steps: 120,
77            deterministic_time: false,
78            max_time_advance_steps: 600,
79            max_time_advance: Duration::from_secs(10),
80            heartbeat_interval: Duration::from_millis(250),
81            session_stale_after: Duration::from_secs(3),
82            max_captures: 32,
83            command_timeout: Duration::from_secs(10),
84            idle_shutdown_after: None,
85        }
86    }
87}