Content
# BattleLuck
BattleLuck is a V Rising dedicated server BepInEx plugin that adds competitive arena game modes, player state management, zone-driven match flow, and optional AI assistance.
## Quick Links
- **[User Guide](docs/user/README.md)** — Installation, commands, configuration
- **[Developer Guide](docs/developer/README.md)** — Architecture, ECS patterns, building
- **[LLM Guide](docs/LLM_GUIDE.md)** — AI setup and event authoring workflow
- **[Publishing Checklist](docs/PUBLISHING_CHECKLIST.md)** — Release preparation
- **[V Rising Mod Wiki](https://wiki.vrisingmods.com/dev/)** — Standard mod development patterns
## Game Modes
| Mode ID | Display Name | Purpose |
|---------|--------------|---------|
| `bloodbath` | Bloodbath | Free-for-all PvP arena |
| `colosseum` | Colosseum | Duel/ELO-focused arena |
| `gauntlet` | Gauntlet | PvE wave survival |
| `siege` | Siege | Objective/team event mode |
| `trials` | Trials | Timed PvE challenge |
| `aievent` | AI Event Test | Deterministic AI-flow test mode |
## Installation
### Prerequisites
- V Rising dedicated server
- [BepInEx 5/6](https://thunderstore.io/c/v-rising/p/BepInEx/BepInExPack_V_Rising/) installed
- .NET 6 runtime (included with modern Windows)
### Build & Deploy
```powershell
# Build
dotnet build BattleLuck.sln -c Release
# Optional: Deploy to server
$env:VRISING_SERVER_ROOT = "C:\Path\To\VRisingServer"
dotnet build BattleLuck.sln -c Release
```
Build output: `bin/Release/net6.0/BattleLuck.dll`
## Configuration
BattleLuck reads config from `config/BattleLuck/`.
### Per-Session Folders
Each game mode lives in a dedicated folder:
```
config/BattleLuck/
├── bloodbath/
│ ├── session.json # Session settings and flow definitions
│ ├── zones.json # Zone definitions
│ └── kit.json # Equipment kits
├── colosseum/
├── gauntlet/
├── siege/
├── trials/
├── aievent/
├── ai_config.json # AI settings (local-only by default)
├── discord_bridge.json # Discord integration (optional)
├── webhook.json # Webhook listener (optional)
└── special_item.json # Special item transformations
```
### Flow Actions
Flow actions are strings inside `session.json` under `flow.enter` / `flow.exit`.
Syntax: `actionName:key=value|key2=value2`
**Core Actions:**
| Action | Parameters | Description |
|--------|-------------|-------------|
| `snapshot.save` | `zoneHash` | Save player state snapshot |
| `snapshot.restore` | `zoneHash` | Restore player snapshot |
| `kit.apply` | `kitId`, `modeId` | Apply kit loadout |
| `heal` | — | Heal player to full |
| `teleport` | `targetZoneHash` | Teleport player |
| `player.buff.apply` | `buffPrefab`, `duration` | Apply buff (-1 = permanent) |
| `spawn.wave` | `waveId`, `count` | Spawn enemy wave |
| `spawn.boss` | `prefab` | Spawn boss |
| `mode.start` | `modeId` | Start a game mode |
| `mode.end` | `modeId` | End a game mode |
| `shrink.zone` | `zoneHash`, `targetRadius` | Shrink zone boundary |
| `timer.start` | `timerId`, `duration` | Start timer |
| `score.add` | `points`, `reason` | Add score |
See [actions_catalog.json](config/BattleLuck/actions_catalog.json) for the complete action reference.
## Core Commands
**Admin commands require admin permissions.**
| Command | Description |
|---------|-------------|
| `.reload` | Reload configuration |
| `.event.start <mode>` | Start a game mode |
| `.event.end <mode>` | End a game mode |
| `.director [mode]` | Show director view for AI/admin |
| `.ai.reload` | Reload AI configuration |
| `.ai.status` | Show AI provider status |
**Player commands:**
| Command | Description |
|---------|-------------|
| `.score` | Show current score |
| `.elo` | Show ELO rating |
| `.exit` | Exit current mode |
| `.toggleenter` | Enter a zone session |
## AI Assistant
By default, BattleLuck is **local-first** and AI is optional. Published configuration disables hosted providers.
To enable AI:
1. Start local inference: `.\scripts\start_vllm.ps1`
2. Set `"enabled": true` in `ai_config.json`
3. Use `.ai.reload` in-game
## Multi-Cloud
BattleLuck is built to run anywhere — **multi-cloud, so fast**. Deploy the same plugin, config,
and AI pipeline across any cloud provider or on-prem V Rising dedicated server with no code changes;
state, snapshots, and integrations stay portable between environments.
## Snapshot System
BattleLuck snapshots player state before mode entry and restores on clean exit, rollback, or penalty-death recovery:
- Position, Health, Blood state
- Equipment, Inventory
- Abilities, Buffs
Snapshots persist under `BepInEx/data/BattleLuck/snapshots/`.
## Dependencies
- [BepInEx](https://github.com/BepInEx/BepInEx) (MIT License)
- [VampireCommandFramework](https://github.com/decaprime/VampireCommandFramework) (MIT License)
Reference implementations credited:
- [KindredCommands](https://github.com/Odjit/KindredCommands) by Odjit (AGPL-3.0)
- [KindredSchematics](https://github.com/odjit/KindredSchematics) by Odjit (AGPL-3.0)
## License
MIT Licensed. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
## Support
- **Discord**: [V Rising Mod Community](https://vrisingmods.com/discord)
- **Wiki**: [V Rising Mod Wiki](https://wiki.vrisingmods.com/)
- **Issues**: [GitHub Issues](https://github.com/coyoteq1/Battleluck-AI/issues)
