Return.h
Source/MassBattle/Public/Fragments/Return.h
概述 Overview
回归行为(return-to-goal)的 fragment 对:配置 FReturn(再触发火线、随机延迟区间、成功门控预算、goal 占位门控、摇摆破解、接受半径、速度乘数)与运行时状态 FReturning(连续预算计时器、goal 占位/采集圈状态、摇摆对、随机延迟掷值、跨帧完成信号)。行为契约:空闲 Agent 被推离 Goal 超过再触发线 RetriggerRadius(0 = 自动 2.5×AcceptanceRadius)并连续保持 InitDelay(区间随机掷值)后触发回归行走;进入 AcceptanceRadius 即停止——两线之间为死区(无回拉、无状态翻转)。单次尝试受 Timeout 总预算门控(等待与行走共用一条连续预算),失败可延迟重锚、可自动关闭(bDisableOnTimeout);bCheckGoalSpace 开启时由 goal 占位探测拦截回归,OscillationWindow 破解反复推离-回归的摇摆链。
Fragment pair for the return-to-goal behavior: config FReturn (push-out re-trigger line, random delay range, success-gate budget, goal-space occupancy gate, oscillation breaker, acceptance radius, speed multiplier) and runtime state FReturning (continuous budget timer, goal occupancy/gather-range markers, the oscillation pair, the random delay roll, a cross-frame completion signal). Behavior contract: an idle agent pushed beyond the re-trigger line RetriggerRadius (0 = auto 2.5× AcceptanceRadius) and held outside continuously through InitDelay (one random draw from a range) triggers a return walk; the walk stops inside AcceptanceRadius — the band between the two lines is a dead band (no pull, no state flip). Each attempt is gated by the total Timeout budget (the wait and the walk share one continuous budget); failure may re-anchor deferred or disable Return outright (bDisableOnTimeout); with bCheckGoalSpace on, goal-space occupancy probes hold the return, and OscillationWindow breaks push-out/return wobble chains.
FReturn USTRUCT
回归行为配置 fragment(FA_MassBattleBaseFragment 派生)。所有字段为策划在 EntityConfig 中可调参数;数值型字段带 ClampMin = "0.0" 编辑器钳制。bEnable / bCheckGoalSpace 的运行时切换(BP/玩法层)经快照同步,锁步各端一致;goal 占位三参数受 EditCondition = bCheckGoalSpace 控制并隐藏显示。
Return-behavior config fragment (derived from FA_MassBattleBaseFragment). All fields are designer-tunable EntityConfig parameters; numeric fields carry ClampMin = "0.0" editor clamps. Runtime toggles of bEnable / bCheckGoalSpace (from BP/gameplay) are snapshot-synced so all lockstep peers agree; the three goal-space params are gated and hidden by EditCondition = bCheckGoalSpace.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
bEnable | bool | false | 是否启用回归行为。禁用时,空闲 Agent 的 Goal 持续跟随当前位置(不自动回归)。运行时切换经快照同步,锁步各端一致。Whether to enable return-to-goal behavior. When disabled, an idle agent's Goal continuously tracks its current location (no automatic return). Runtime toggles are snapshot-synced so all lockstep peers agree. |
bCheckGoalSpace | bool | false | goal 占位门控总开关。false(默认):无视占位直接回归(无准入等待、无途中暂停、无每帧采集判定)硬挤进去,由 PBD 碰撞解决堆积。true:goal 被占则拦停回归——触发前准入等待并按 SpaceQueryInterval 重探,途中占用者暂停行走直至释放。运行时切换经快照同步。Goal-space occupancy gate master switch. False (default): the agent returns regardless of occupancy (no admission hold, no mid-walk pause, no per-frame gather verdict) and pushes in — PBD collision resolves the pile. True: an occupied goal holds the return — pre-trigger admission waits & re-probes every SpaceQueryInterval, a mid-walk occupant pauses the walk until freed. Runtime toggles are snapshot-synced. |
bDisableOnTimeout | bool | false | Timeout 失败后自动关闭 Return。false(默认):失败的尝试保持 Return 开启——后续被推再触发新尝试(含延迟重锚)。true:首次 Timeout 失败即关闭该 Agent 的 Return(运行时 bEnable=false,快照同步)——goal 从此跟随其位置(不再回归),直到玩法层重新开启。最强版就地安家:试一次、失败、接受现状。Auto-disable Return on Timeout failure. False (default): a failed attempt keeps Return enabled — later pushes trigger fresh attempts (with the deferred re-anchor). True: the FIRST Timeout failure turns Return OFF for this agent (runtime bEnable=false, snapshot-synced) — the goal then follows its position permanently until gameplay re-enables it. The strongest settle-underfoot form: try, fail once, accept wherever you stand. |
InitDelay | FVector2f | (0, 0) | 回归启动延迟区间(秒)——X=最小,Y=最大。每个出界周期用 Agent 的确定性 RandomStream 在 [X,Y] 掷一次随机值,打散群体同步触发(不再齐波回归)。须连续停留在外(带外)完整的掷出延迟;回到带内重掷。注意:Timeout 预算在此等待期间即开始消耗。Y<X 视为固定 X;(0,0) = 无延迟。Delay range (seconds) before the return actually starts — X = min, Y = max. Each out-period draws ONE random value in [X,Y] from the agent's deterministic RandomStream, desynchronizing group triggers (no synchronized return waves). The agent must remain continuously outside for the full drawn delay; drifting back inside re-rolls. NOTE: the Return.Timeout budget is ALREADY burning during this wait. Y<X behaves as fixed X; (0,0) = no delay. |
SpaceQueryInterval | float | 1.f | goal 空间探测到被占期间的重探周期(秒)。0 = InitDelay 满足后每帧探测(每个被阻塞 Agent 每帧一次网格查询——开销大)。亦为回归进行中的途中复探周期。仅 bCheckGoalSpace 开启时可编辑。Re-probe period (seconds) while the goal-space probe finds the goal occupied. 0 = probe every frame once InitDelay is satisfied (a grid query per blocked agent per frame — expensive). Also the mid-walk re-probe cadence while a return is in progress. Editable only when bCheckGoalSpace is on. |
SpaceProbeMult | float | 1.f | goal 空间探测圆(双方正圆对测)的尺寸乘数,Clamp 0–10:缩放自身侧半径 = max(自身胶囊包围球, 自身避障椭圆长轴)。< 1 缩小(宽松——允许回归到更紧的空位,如槽位间距小于半径和的肩并肩阵型);> 1 放大(严格——归位前要求 goal 周围留出额外净空)。1 = 精确自身圆;0 = 退化为点对占位者测试。仅 bCheckGoalSpace 开启时可编辑。Size multiplier on the goal-space probe CIRCLE (perfect-circle overlap both sides), clamped 0–10: scales the self-side radius = max(self capsule bounding sphere, self avoid-ellipse major axis). < 1 shrinks the probe (lenient — lets an agent return into a tighter fit, e.g. shoulder-to-shoulder formations whose slots sit closer than the radius sum); > 1 grows it (stricter — demands extra clearance around the goal). 1 = exact self circle; 0 = degenerate point-vs-occupant test. Editable only when bCheckGoalSpace is on. |
SpaceProbeTolerance | float | 100.f | 采集圈内 goal 判定的邻域容差(cm):goal 位于自身避障采集范围内时,每帧邻居测试还会探测此半径内的偏移点——任一偏移空闲即放行/继续回归;Agent 仍以原 goal 为目标,经碰撞解决落在空闲处。远 goal 空间探测(超出采集范围)只测中心点——接近后容差自然接管。建议 ≤ AcceptanceRadius 以保证偏移点在到达停止距离内。0 = 严格精确位置测试。仅 bCheckGoalSpace 开启时可编辑。Neighborhood tolerance (cm) for the in-gather-range goal verdict: when the goal lies inside self's avoidance gather range, the per-frame neighbor test also probes offset points within this radius — any free offset admits/continues the return; the agent still targets the original goal and settles at the free spot through collision resolution. The far-goal spatial probe tests the exact center only — tolerance takes over as the agent approaches. Keep ≤ AcceptanceRadius so free offsets stay within the arrival stop distance. 0 = strict exact-goal test. Editable only when bCheckGoalSpace is on. |
Timeout | float | 0.f | 成功门控:单次回归尝试的总时间预算,从被推过再触发线的第一刻起算——InitDelay 等待、被占暂停与行走全部消耗它(被永久推移的 Agent 无需行走一轮即放弃旧 goal)。到期即判定失败:停止行走、放弃旧 goal,重锚延迟到下一轮尝试启动那一刻。0 = 无门控(回归直到成功)。Success gate: total time budget for one return ATTEMPT, counted from the FIRST push beyond the retrigger line — the InitDelay wait, blocked-probe holds AND the active walk all burn it (a forever-displaced agent abandons the old goal without a single walk). On expiry the attempt is judged FAILED: the walk stops, the OLD goal is abandoned and the re-anchor is DEFERRED to the next attempt's start. 0 = no gate (return until success). |
OscillationWindow | float | 0.f | 摇摆破解:回归成功后,若在此秒数内再次触发回归,判定为摇摆(被反复推离又回归)——成功门控累计不重置,继承上次尝试的累计,摇摆链最终耗尽 Timeout 就地安家。链内每次成功都会重新上膛窗口并暂存累计总额。与 Timeout 组合生效(Timeout = 0 时无效果)。0 = 每次尝试全新门控预算(默认)。Oscillation wobble-breaker: after a return SUCCEEDS, if a new return triggers within this many seconds the agent is judged wobbling (pushed out and returning over and over) — the success-gate accumulator is NOT reset; it carries the previous attempt's accumulation, so the wobble chain eventually exhausts Timeout and settles underfoot. Each success inside the chain re-arms the window and re-stashes the running total. Composes with Timeout (no effect when Timeout = 0). 0 = every attempt gets a fresh gate budget (default). |
AcceptanceRadius | float | 100.f | 仅作到达停止线:回归行走进入该半径即停止。推出再触发线是 RetriggerRadius;两线之间为死区(无回拉、无状态翻转)。Arrival stop line ONLY: a returning walk stops once within this distance of Goal. The push-out re-trigger line is RetriggerRadius; the band between the two is a dead band (no pull, no state flip). |
RetriggerRadius | float | 0.f | 推出再触发火线:空闲 Agent 被推离 Goal 超过此距离(连续保持 InitDelay)才触发回归行走。0 = 自动(2.5 × AcceptanceRadius)。须大于 AcceptanceRadius 以留出死区——死区内无任何回拉(Agent 接受位移);只有超出此线的位移才升级为完整回归行走(冲锋冲散后的恢复不受影响)。解析值 = max(配置或自动值, AcceptanceRadius),见 GetRetriggerRadius()。Push-out re-trigger fire line: an idle agent pushed beyond this distance from Goal (held outside continuously through InitDelay) triggers a return walk. 0 = auto (2.5 × AcceptanceRadius). Keep > AcceptanceRadius to leave a dead band — inside it nothing pulls (agents accept displacement); only displacement beyond this line escalates to a full return walk. Resolved = max(value-or-auto, AcceptanceRadius); see GetRetriggerRadius(). |
MoveSpeedMult | float | 1.f | 回归过程中的移动速度乘数。Movement speed multiplier while returning. |
方法 Methods
解析后的再触发火线:显式值;RetriggerRadius 为 0 时自动取 2.5 × AcceptanceRadius;下限钳到 AcceptanceRadius——错误调参不会退化回无滞回抖动。
Resolved re-trigger fire line: the explicit value; auto (2.5 × AcceptanceRadius) when RetriggerRadius is 0; floored at AcceptanceRadius so a mis-tuned value can never reintroduce no-hysteresis chatter.
Input
无参数。
No parameters.
Output
返回 max(RetriggerRadius > 0 ? RetriggerRadius : AcceptanceRadius × 2.5, AcceptanceRadius);无副作用。
Returns max(RetriggerRadius > 0 ? RetriggerRadius : AcceptanceRadius × 2.5, AcceptanceRadius); no side effects.
FReturning USTRUCT
回归行为运行时状态 fragment(FA_MassBattleBaseFragment 派生),由行为 / 反应 / 移动处理器逐帧推进。ElapsedTime 连续复用:先累积 InitDelay,满足后无缝继续作为回归成功门控(Return.Timeout)的预算——等待与行走共用同一条连续预算(触发时不再清零)。除 ElapsedTime / bJustFinished 外,新增字段均带 UPROPERTY() 以支持快照序列化。
Return-behavior runtime state fragment (derived from FA_MassBattleBaseFragment), advanced per frame by the behavior/reaction/move processors. ElapsedTime is reused continuously: it accumulates InitDelay first, then CONTINUES seamlessly as the active-return success-gate (Return.Timeout) budget — the wait and the walk share one continuous budget (the trigger no longer resets it). Beyond ElapsedTime / bJustFinished, all new fields carry UPROPERTY() for snapshot serialization.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
ElapsedTime | float | 0.f | Agent 被推离 AcceptanceRadius 以来累计的时间(秒),先累积 InitDelay,满足后无缝继续作为成功门控预算。Elapsed time since the agent was pushed outside AcceptanceRadius. Accumulates InitDelay first; once satisfied the accumulation CONTINUES seamlessly as the active-return success-gate budget. |
SpaceGateCooldown | float | 0.f | goal 空间探测到被占后的下次探测倒计时(配合 Return.SpaceQueryInterval)。UPROPERTY 以支持快照序列化。Countdown to the next goal-space probe after the probe found the goal occupied (with Return.SpaceQueryInterval). UPROPERTY for snapshot serialization. |
bGoalBlocked | bool | false | 途中 goal 复探结果(回归进行中):ReactionProcessor 在 ReturningFlag 激活期间按 SpaceQueryInterval 节奏复探 goal 占用;为真时 MoveProcessor 暂停行走(零期望方向,保持回归态)——门控照常累计,Return.Timeout 仍为出口;释放则恢复。每次复探刷新;触发、Reset() 与回归成功时清零。UPROPERTY 以支持快照序列化。Mid-walk goal re-probe result (active return): ReactionProcessor re-probes goal occupancy on the SpaceQueryInterval cadence while ReturningFlag is active; true pauses the walk in MoveProcessor (zero desired direction, keeps ReturningFlag) — the success gate keeps counting and Return.Timeout stays the exit; freed → resume. Refreshed on every probe; cleared at trigger, in Reset() and on return success. UPROPERTY for snapshot serialization. |
bGoalCoveredByGather | bool | false | goal 位于采集圈内标记,由 MoveProcessor 每帧写入(Idle 行为、Return 开启):goal 位于自身 RVO 采集范围内时,逐帧采集的邻居列表每帧刷新 bGoalBlocked——权威、无查询、无周期;Reaction 的节流空间探测只服务远 goal 情形。归属:圈内→Move 邻居判定写 bGoalBlocked;圈外→Reaction 探测持有。陈旧性由 Return.Timeout 兜底。UPROPERTY 以支持快照序列化。Goal-inside-gather-range marker, written per frame by MoveProcessor (Idle behavior, Return enabled): when the goal lies inside self's RVO gather range, the per-frame gathered neighbor list refreshes bGoalBlocked EVERY frame — authoritative, no query, no SpaceQueryInterval cadence; Reaction's throttled spatial probe only serves the far-goal case. Ownership: covered → Move's neighbor test writes bGoalBlocked; not covered → Reaction's probe owns it. Staleness bounded by Return.Timeout. UPROPERTY for snapshot serialization. |
OscillationWindowLeft | float | 0.f | 摇摆窗口剩余倒计时(Return.OscillationWindow):每次回归成功结束时上膛——MoveProcessor 暂存本次门控累计并武装倒计时(先于 ElapsedTime 清零);ReactionProcessor 逐帧递减,存活期内再触发即继承暂存而非重置门控。刻意在 Reset() 中存活——否则 finish→行为切换 Reset→再触发链会清掉它们;经倒计时自然过期,窗口外的下次触发与 !bEnable 时清零。UPROPERTY 以支持快照序列化。Oscillation window countdown left (Return.OscillationWindow): armed at every SUCCESSFUL return finish — MoveProcessor stashes the attempt's success-gate accumulation into CarriedGateTime and arms the countdown BEFORE zeroing ElapsedTime; ReactionProcessor ticks the countdown and, on a trigger while still live, carries the stash instead of resetting the gate. DELIBERATELY survives Reset() — the finish→BehaviorProcessor Reset→re-trigger chain would wipe them otherwise; they self-expire via the countdown and are cleared at the next out-of-window trigger and on !bEnable. UPROPERTY for snapshot serialization. |
CarriedGateTime | float | 0.f | 摇摆对的暂存门控累计额(见 OscillationWindowLeft)。UPROPERTY 以支持快照序列化。The oscillation pair's stashed success-gate accumulation (see OscillationWindowLeft). UPROPERTY for snapshot serialization. |
RolledInitDelay | float | -1.f | 随机 InitDelay 掷值(区间 [X,Y]):每个出界周期用确定性 RandomStream 在首个累计帧掷一次;-1 = 未掷。回到带内随 ElapsedTime 一并清零(下周期重掷)。UPROPERTY 以支持快照序列化。Random InitDelay roll (the [X,Y] range): drawn ONCE per out-period from the agent's deterministic RandomStream on the first accumulating frame; -1 = not rolled yet. Cleared together with ElapsedTime when back inside (fresh roll next out-period). UPROPERTY for snapshot serialization. |
bPendingFailReset | bool | false | 延迟失败重锚(Return.Timeout):尝试超时时置位——旧 goal 即刻作废但不改写 Goal;下一轮回归尝试启动时重新安家(Goal = 该刻位置,含 InitDelay 期间的推移漂移)。经 Reset() 清除——行为切换(追击/巡逻…)本就会替换 goal,过期待定随之作废。UPROPERTY 以支持快照序列化。Deferred fail re-anchor (Return.Timeout): set when an attempt TIMES OUT — the old goal is abandoned at fail time but Goal is NOT rewritten; the re-anchor (Goal = the agent's position at that moment, post-InitDelay push-drift) fires at the NEXT return trigger. Cleared by Reset() — a behavior switch (chase/patrol...) replaces the goal anyway, voiding a stale pending. UPROPERTY for snapshot serialization. |
bJustFinished | bool | false | 跨帧转换信号——本轮回归刚完成。UPROPERTY 以支持 snapshot 序列化。Cross-frame transition signal — the return cycle just finished. UPROPERTY required for snapshot serialization. |
方法 Methods
复位状态:ElapsedTime 归零、SpaceGateCooldown 归零、bGoalBlocked / bGoalCoveredByGather 清 false、bJustFinished 清 false、RolledInitDelay 置 -1(下个出界周期重掷)。刻意不清 OscillationWindowLeft / CarriedGateTime——它们须活过成功后的行为切换 Reset(见字段注释),经倒计时自然过期。用于回归循环重启、行为切换或实体复用。
Resets state: ElapsedTime to 0, SpaceGateCooldown to 0, bGoalBlocked / bGoalCoveredByGather to false, bJustFinished to false, RolledInitDelay to -1 (fresh roll next out-period). DELIBERATELY does NOT clear OscillationWindowLeft / CarriedGateTime — they must outlive the post-finish behavior-switch reset (see the field comment) and self-expire via the countdown. Used on return-cycle restart, behavior switch or entity reuse.
Input
无参数。
No parameters.
Output
无返回值。副作用:上述成员复位(摇摆对保留)。
No return value. Side effect: the members above reset (the oscillation pair kept).
补充说明 Notes
旧版的 Threshold(触发阈值)、StuckSpeed / StuckTime(卡住判定)与注释预留的 MaxTries / TryCount 已全部移除:触发改由 RetriggerRadius 再触发火线驱动,失败判定改由 Timeout 成功门控预算承担。
The legacy Threshold (trigger threshold), StuckSpeed / StuckTime (stuck detection) and the commented-out MaxTries / TryCount reservations have all been removed: triggering is now driven by the RetriggerRadius fire line, and failure judgment by the Timeout success-gate budget.
管线角色 Pipeline Role
FReturn / FReturning 在 MassBattle 管线中的位置:由 MassBattleAgentBehaviorProcessor(回归状态机)、MassBattleAgentMoveProcessor / MassBattleAgentMoveProcessorFP(回归移动:途中暂停、采集圈内逐帧刷新 bGoalBlocked、成功时暂存门控累计并武装摇摆窗口)、MassBattleAgentReactionProcessor(按 SpaceQueryInterval 节奏的 goal 占位复探、递减摇摆倒计时)读写。与 Moving(Goal)联动。
Position of FReturn / FReturning in the MassBattle pipeline: read/written by MassBattleAgentBehaviorProcessor (return state machine), MassBattleAgentMoveProcessor / MassBattleAgentMoveProcessorFP (return movement: mid-walk pause, per-frame bGoalBlocked refresh inside the gather range, stashing the gate accumulation and arming the oscillation window on success) and MassBattleAgentReactionProcessor (goal-occupancy re-probes on the SpaceQueryInterval cadence, ticking the oscillation countdown). Interacts with Moving (Goal).