109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# 59 — BP_PatrolPath
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`Actor`
|
||
|
||
### Dependencies
|
||
- [`BP_EnemyBase`](58_BP_EnemyBase.md) — AI pawn using the path
|
||
- [`BPC_AIControllerBase`](55_BPC_AIControllerBase.md) — Waypoint consumer
|
||
- [`DA_AIProfile`](../12-content/63_DA_AIProfileDataAsset.md) — Patrol behavior config
|
||
|
||
### Purpose
|
||
Waypoint-based patrol route for AI characters. Defines a sequence of points (spline or actor array) that AI follows during patrol state. Supports looping, ping-pong, random selection, and conditional stops. Visualized in-editor with spline or point indicators for level designers.
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `PatrolPoints` | Array<FVector> | World-space waypoints |
|
||
| `PatrolMode` | EPatrolMode | Sequence mode |
|
||
| `bIsLooping` | Bool | Restart from first after last |
|
||
| `bIsPingPong` | Bool | Reverse direction at end |
|
||
| `PointRadius` | Float | Acceptance radius for reaching a point |
|
||
| `WaitTimeAtPoint` | Float | Pause at each waypoint (seconds) |
|
||
| `bRandomizeOrder` | Bool | Shuffle points on each loop |
|
||
| `bUseSpline` | Bool | Draw spline between points |
|
||
| `SplineComponent` | USplineComponent | Optional spline path |
|
||
| `bDrawDebug` | Bool | Editor visualization toggle |
|
||
| `DebugPointColor` | FColor | Point color in editor |
|
||
| `ConnectedAI` | Array<BPC_AIControllerBase> | AI using this path |
|
||
|
||
### Enums
|
||
|
||
| Enum | Values | Description |
|
||
|------|--------|-------------|
|
||
| `EPatrolMode` | Sequential, Random, PingPong, Reverse | Point selection order |
|
||
|
||
### Functions
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `GetNextPatrolPoint` | CurrentIndex: Int | FVector, NewIndex: Int | Next waypoint based on mode |
|
||
| `GetPatrolStartPoint` | — | FVector, StartIndex: Int | First point |
|
||
| `GetPatrolPointCount` | — | Int | Total points |
|
||
| `GetPatrolPointByIndex` | Index: Int | FVector | Specific point |
|
||
| `AddPatrolPoint` | Location: FVector | — | Add waypoint |
|
||
| `RemovePatrolPoint` | Index: Int | — | Remove waypoint |
|
||
| `ClearPatrolPoints` | — | — | Reset path |
|
||
| `SetPatrolMode` | Mode: EPatrolMode | — | Change movement pattern |
|
||
| `IsPatrolComplete` | CurrentIndex: Int | Bool | End of path |
|
||
| `RegisterAIUser` | AIController: BPC_AIControllerBase | — | Track who uses this path |
|
||
| `UnregisterAIUser` | AIController: BPC_AIControllerBase | — | Remove usage |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[GetNextPatrolPoint(CurrentIndex)]
|
||
└─► If PatrolMode == Sequential:
|
||
NewIndex = CurrentIndex + 1
|
||
If NewIndex >= PatrolPoints.Num():
|
||
If bIsLooping: NewIndex = 0
|
||
Else: return Last point and IsPatrolComplete = true
|
||
└─► If PatrolMode == Random:
|
||
NewIndex = Random integer in range [0, Points.Num - 1]
|
||
Exclude CurrentIndex to avoid standing still
|
||
└─► If PatrolMode == PingPong:
|
||
If going forward:
|
||
NewIndex = CurrentIndex + 1
|
||
If NewIndex >= PatrolPoints.Num(): reverse direction
|
||
If going backward:
|
||
NewIndex = CurrentIndex - 1
|
||
If NewIndex < 0: reverse direction
|
||
└─► If PatrolMode == Reverse:
|
||
NewIndex = CurrentIndex - 1
|
||
If NewIndex < 0:
|
||
If bIsLooping: NewIndex = Points.Num - 1
|
||
Else: IsPatrolComplete = true
|
||
└─► Return PatrolPoints[NewIndex], NewIndex
|
||
```
|
||
|
||
### Editor Visualization
|
||
|
||
```
|
||
[OnConstruction]
|
||
└─► If bDrawDebug:
|
||
For each point:
|
||
DrawDebugSphere(Point, PointRadius, 12, DebugPointColor)
|
||
If bUseSpline:
|
||
SplineComponent.SetSplinePoints(PatrolPoints, ESplineCoordinateSpace::World)
|
||
Else:
|
||
Draw lines between consecutive points
|
||
```
|
||
|
||
### Communications With
|
||
|
||
| Target | Method | Why |
|
||
|--------|--------|-----|
|
||
| [`BPC_AIControllerBase`](55_BPC_AIControllerBase.md) | Direct call | AI requests next waypoint |
|
||
| [`BP_EnemyBase`](58_BP_EnemyBase.md) | Direct (via controller) | Move-to destination |
|
||
| Level Designer | Editor visualization | Place and configure in world |
|
||
|
||
### Reuse Notes
|
||
- World-placed actor, assignable to any AI via DA_AIProfile or direct reference
|
||
- Multiple AI can share one patrol path (squad patrol)
|
||
- Spline mode allows smooth curved paths (for flying/gliding enemies)
|
||
- Works with any AI that reads patrol index from blackboard |