mirror of
https://github.com/2revoemag/PSF-BotServer.git
synced 2026-04-22 12:25:21 +00:00
feat: Add bot player system for PlanetSide population
Initial implementation of server-side bots that: - Spawn as real Player entities with full equipment - Move and broadcast position updates (10 tick/sec) - Take damage and die with backpack drops - Respawn after death - Combat system with accuracy model (adjustment vs recoil) Includes project documentation in bot-docs/ and Claude agent helpers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2revoemag
parent
9646b3f99e
commit
2e5b5e0dbd
17 changed files with 3813 additions and 0 deletions
291
bot-docs/POC_PLAN.md
Normal file
291
bot-docs/POC_PLAN.md
Normal file
|
|
@ -0,0 +1,291 @@
|
|||
# PlanetSide Bots - Proof of Concept Plan
|
||||
|
||||
## Goal
|
||||
Get a single bot to spawn, be visible to clients, and perform basic actions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Research & Setup (DONE)
|
||||
|
||||
- [x] Clone PSF-LoginServer
|
||||
- [x] Analyze codebase architecture
|
||||
- [x] Identify Player entity system
|
||||
- [x] Find existing AI patterns (AutomatedTurretBehavior)
|
||||
- [x] Document integration points
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: "Hello World" Bot
|
||||
|
||||
### Objective
|
||||
Spawn a bot entity that appears in the game world as a player character.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 1.1 Understand Player Creation Flow
|
||||
- [ ] Trace how a real player is created when they log in
|
||||
- [ ] Find `Player` instantiation code
|
||||
- [ ] Find zone registration code (`Zone.AddPlayer` or similar)
|
||||
- [ ] Find GUID allocation for new entities
|
||||
|
||||
#### 1.2 Create Minimal Bot Infrastructure
|
||||
- [ ] Create `src/main/scala/net/psforever/objects/bot/` directory
|
||||
- [ ] Create `Bot.scala` - wrapper or extension of Player
|
||||
- [ ] Create `BotActor.scala` - minimal actor (just keeps bot alive)
|
||||
|
||||
#### 1.3 Bot Spawning
|
||||
- [ ] Find how to spawn a player at a SpawnPoint without client
|
||||
- [ ] Allocate GUID for bot
|
||||
- [ ] Register bot in zone
|
||||
- [ ] Broadcast bot's existence to other players
|
||||
|
||||
#### 1.4 Validation
|
||||
- [ ] Connect real client to server
|
||||
- [ ] Verify bot appears as a player character
|
||||
- [ ] Bot should be standing still at spawn location
|
||||
|
||||
### Questions to Answer
|
||||
- Can we create a Player without Avatar from database?
|
||||
- Do we need to fake an Account/Character entry?
|
||||
- What minimum packets must be sent to make bot visible?
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Moving Bot
|
||||
|
||||
### Objective
|
||||
Bot moves through the world and other players can see it moving.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 2.1 PlayerStateMessage Broadcasting
|
||||
- [ ] Understand how player position updates are broadcast
|
||||
- [ ] Find the packet: `PlayerStateMessage`
|
||||
- [ ] Implement position update loop in BotActor
|
||||
|
||||
#### 2.2 Simple Movement
|
||||
- [ ] Bot walks forward
|
||||
- [ ] Bot turns (change orientation)
|
||||
- [ ] Movement speed matches infantry walking
|
||||
|
||||
#### 2.3 Patrol Behavior
|
||||
- [ ] Bot walks between two points
|
||||
- [ ] Bot stops, turns, walks back
|
||||
|
||||
### Success Criteria
|
||||
- Real player sees bot walking around
|
||||
- Bot movement is smooth (not teleporting)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Combat Bot
|
||||
|
||||
### Objective
|
||||
Bot can detect enemies and shoot at them.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 3.1 Vision System
|
||||
- [ ] Implement FOV cone check (60-90 degrees)
|
||||
- [ ] Detect players in range
|
||||
- [ ] Filter by faction (don't shoot friendlies)
|
||||
|
||||
#### 3.2 Target Tracking
|
||||
- [ ] Store current target reference
|
||||
- [ ] Turn to face target (orientation updates)
|
||||
- [ ] Lose target when out of range/sight
|
||||
|
||||
#### 3.3 Shooting
|
||||
- [ ] Find weapon fire packets (`ChangeFireStateMessage_Start`, `WeaponFireMessage`)
|
||||
- [ ] Implement firing at target
|
||||
- [ ] Basic accuracy (not perfect, not terrible)
|
||||
|
||||
#### 3.4 Taking Damage
|
||||
- [ ] Bot receives damage normally (via PlayerControl)
|
||||
- [ ] Bot dies when HP reaches 0
|
||||
- [ ] Bot respawns after death
|
||||
|
||||
### Success Criteria
|
||||
- Bot shoots at enemy players
|
||||
- Bot can be killed
|
||||
- Bot respawns
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Smart Bot
|
||||
|
||||
### Objective
|
||||
Bot makes tactical decisions.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 4.1 Health-Based Retreat
|
||||
- [ ] Track bot's HP
|
||||
- [ ] Retreat when HP below threshold
|
||||
- [ ] Find cover or run toward spawn
|
||||
|
||||
#### 4.2 Ammunition Management
|
||||
- [ ] Track ammo count
|
||||
- [ ] Retreat to resupply when empty
|
||||
|
||||
#### 4.3 V-Menu Communication
|
||||
- [ ] Bot sends VVV when needs help
|
||||
- [ ] Bot sends VNG when in vehicle without gunner
|
||||
- [ ] Proper chat message format
|
||||
|
||||
### Success Criteria
|
||||
- Bot retreats when hurt
|
||||
- Bot calls for help appropriately
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Bot Classes
|
||||
|
||||
### Objective
|
||||
Different bot types with different behaviors.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 5.1 Class Definitions
|
||||
- [ ] Define loadouts for each class (Driver, Support, Hacker, AV, MAX)
|
||||
- [ ] Create certification sets per class
|
||||
- [ ] Assign behavior weights per class
|
||||
|
||||
#### 5.2 Class-Specific Behavior
|
||||
- [ ] Support: Prioritize healing/repairing
|
||||
- [ ] Hacker: Prioritize hacking doors/objectives
|
||||
- [ ] AV: Prioritize anti-vehicle combat
|
||||
- [ ] MAX: Heavy combat behavior
|
||||
|
||||
#### 5.3 Vet & Ace Classes
|
||||
- [ ] Vet: Multi-role capability
|
||||
- [ ] Ace: Command behavior, last to logout
|
||||
|
||||
### Success Criteria
|
||||
- Multiple bot types visible
|
||||
- Each type behaves differently
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Population Management
|
||||
|
||||
### Objective
|
||||
Bots scale with player population.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 6.1 BotManager
|
||||
- [ ] Track real player count per faction
|
||||
- [ ] Calculate target bot count
|
||||
- [ ] Spawn/despawn bots to maintain balance
|
||||
|
||||
#### 6.2 Graceful Despawn
|
||||
- [ ] Non-Ace bots leave first
|
||||
- [ ] Ace leaves last
|
||||
- [ ] Bots "log out" naturally (not poof)
|
||||
|
||||
#### 6.3 Faction Balance
|
||||
- [ ] Equal bots per faction
|
||||
- [ ] Adjust for real player imbalance?
|
||||
|
||||
### Success Criteria
|
||||
- Server maintains ~100 bots per faction when empty
|
||||
- Bots reduce as real players join
|
||||
- Ace is last bot standing per faction
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Team Coordination
|
||||
|
||||
### Objective
|
||||
Bots work together and follow orders.
|
||||
|
||||
### Tasks
|
||||
|
||||
#### 7.1 Order System
|
||||
- [ ] Ace issues attack/defend orders
|
||||
- [ ] Bots receive and follow orders
|
||||
- [ ] Order priority system
|
||||
|
||||
#### 7.2 Help Response
|
||||
- [ ] Bots respond to VNG/VNH/VVV
|
||||
- [ ] Check if can help
|
||||
- [ ] Navigate to requester
|
||||
|
||||
#### 7.3 Celebration Coordination
|
||||
- [ ] Coordinate V-menu celebrations
|
||||
- [ ] Staggered timing
|
||||
- [ ] Limited responders (1-6)
|
||||
|
||||
### Success Criteria
|
||||
- Bots attack/defend as ordered
|
||||
- Bots help each other
|
||||
- Celebrations feel natural
|
||||
|
||||
---
|
||||
|
||||
## Development Environment Setup
|
||||
|
||||
### Prerequisites
|
||||
- Java 8 JDK
|
||||
- sbt (Scala Build Tool)
|
||||
- PostgreSQL 10+
|
||||
- PlanetSide client (version 3.15.84.0)
|
||||
|
||||
### Build & Run
|
||||
```bash
|
||||
cd PSF-LoginServer
|
||||
sbt compile
|
||||
sbt server/run
|
||||
```
|
||||
|
||||
### Testing Approach
|
||||
1. Run server locally
|
||||
2. Connect with PS client
|
||||
3. Observe bot behavior
|
||||
4. Iterate
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| Player without SessionActor breaks things | Medium | High | May need dummy SessionActor |
|
||||
| GUID allocation conflicts | Medium | High | Coordinate with existing GUID system |
|
||||
| Performance with 300+ bots | Medium | Medium | Profile early, optimize as needed |
|
||||
| Network overhead for bot updates | Low | Medium | Batch updates, reduce frequency |
|
||||
| Client can't render many players | Low | High | Test with max players early |
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Phase 1 Success
|
||||
- 1 bot visible in game world
|
||||
|
||||
### Phase 3 Success
|
||||
- Bot engages in combat
|
||||
|
||||
### Phase 5 Success
|
||||
- Multiple bot classes working
|
||||
|
||||
### Phase 7 Success (MVP)
|
||||
- 100+ bots per faction
|
||||
- Dynamic population scaling
|
||||
- Team coordination
|
||||
- "Feels like PlanetSide"
|
||||
|
||||
---
|
||||
|
||||
## Estimated Complexity
|
||||
|
||||
| Phase | Complexity | Notes |
|
||||
|-------|------------|-------|
|
||||
| 1 | Medium | Unknown integration points |
|
||||
| 2 | Low | Straightforward once Phase 1 works |
|
||||
| 3 | Medium | Combat systems are complex |
|
||||
| 4 | Low | Building on Phase 3 |
|
||||
| 5 | Medium | Many classes to implement |
|
||||
| 6 | Low | Straightforward management |
|
||||
| 7 | High | Coordination is complex |
|
||||
Loading…
Add table
Add a link
Reference in a new issue