# BattleLuck BattleLuck is a V Rising BepInEx plugin focused on competitive arena-style modes, player state snapshots, zone-driven match flow, optional AI assistance, Discord/webhook integrations, and server-side event control. ## 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 | ## Commands BattleLuck commands are registered through VampireCommandFramework. 🔒 = admin only. ### Admin Commands | Command | Description | | --- | --- | | `.ai.event` 🔒 | Replay AI event flow (start, score, elimination, end) without entering a zone | | `.ai.reload` 🔒 | Reload AI configuration and restart service | | `.ai.status` 🔒 | Show detailed AI assistant status | | `.ai.test` 🔒 | Test AI assistant with a sample query | | `.autotrash` 🔒 | Toggle auto-trash for dropped items in mode zones | | `.autotrash.status` 🔒 | Show auto-trash stats | | `.debugabilities` 🔒 | Print all discovered AbilityGroup prefabs from the server | | `.debugslots` 🔒 | Print combat key slot resolution status | | `.event.clearburning` 🔒 | Remove burning penalty from all players | | `.event.end` 🔒 | End all sessions for a mode and clear burning | | `.event.endall` 🔒 | End ALL active sessions and clear all burning | | `.event.forceenter` 🔒 | Force a player into a mode | | `.event.forceexit` 🔒 | Force a player out of their current event | | `.event.start` 🔒 | Start an event mode (teleports you in) | | `.event.status` 🔒 | Show all active events and player counts | | `.freebuild` 🔒 | Toggle building restrictions off/on | | `.kick` 🔒 | Kick player from session | | `.pause` 🔒 | Pause all active sessions | | `.reload` 🔒 | Reload configs from disk | | `.resume` 🔒 | Resume paused sessions | | `..scanbufs [filter]` 🔒 | Scan live prefabs for buffs | | `..scanitems ` 🔒 | Scan live prefabs for items | | `..scanprefabs [maxResults]` 🔒 | Scan live prefabs matching a filter | | `.setwinner` 🔒 | Set winner and end session | | `..spawntest ` 🔒 | Test-spawn a unit at your position | | `..spawnwave ` 🔒 | Test-spawn a wave of enemies | | `..stashnpc [sourceNetId|allteam] [maxDistance] [sameTeam] [minStack] [maxStacks] [itemFilter]` 🔒 | Transfer items from NPC source(s) to destination entity | | `.zoneinfo` 🔒 | Show zone stats and player counts | ### DataExport Commands | Command | Description | | --- | --- | | `.discoverkits` 🔒 | Auto-discover the best weapon/armor/tile/ability prefabs from live game data and export kit.json template | | `.exportmods` 🔒 | Export all loaded mod data (plugins, prefabs, APIs) to JSON | | `.exportplugins` 🔒 | Export loaded BepInEx plugin info to JSON | | `.exportprefabs` 🔒 | Export server live prefab collection to JSON | | `.findtiles` 🔒 | Search live prefabs for tile/wall/floor building pieces | | `.searchprefab` 🔒 | Search ALL live prefabs by name pattern (e.g. 'Item_Weapon_Sword', 'AB_Chaos', 'Item_Armor') | | `.validateprefabs` 🔒 | Check if BattleLuck prefab GUIDs exist in the game's entity map | ### Mode Commands | Command | Description | | --- | --- | | `.force` 🔒 | Teleport to mode's zone and auto-start session | | `.modeend` 🔒 | Force-end all sessions for a mode | | `.modeinfo` 🔒 | Show mode configuration details | | `.modelist` 🔒 | List all registered game modes | | `.modestart` 🔒 | Start a game mode manually | ### Mutator Commands | Command | Description | | --- | --- | | `.mutatorclear` 🔒 | Clear all mutators | | `.mutatordisable` 🔒 | Disable a mutator | | `.mutatorenable` 🔒 | Enable a mutator | | `.mutatorlist` | List available mutators | ### Player Commands | Command | Description | | --- | --- | | `.actions` | Show valid actions for the current mode | | `..ai ` | Chat with the AI assistant | | `.aistatus` | Show AI assistant status and settings | | `.elo` | Show Elo ratings for Colosseum mode | | `.exit` | Force exit current zone session | | `.help` | Show available BattleLuck commands | | `.kit` 🔒 | Apply full end-game kit to yourself | | `.score` | Show current scoreboard | | `.toggleenter` | Enter a zone session. Use: .toggleenter [modeName] | | `.toggleleave` | Properly leave the current zone session | ### Team Commands | Command | Description | | --- | --- | | `.teamaccept` | Accept team invite | | `.teamcreate` | Create a team | | `.teaminvite` | Invite player to your team | | `.teamleave` | Leave your team | | `.teamlist` | List all teams | ## Configuration Layout BattleLuck reads config from `config/BattleLuck/`. ### Per-mode folders Each mode folder contains: - `session.json` - `zones.json` - `flow_enter.json` - `flow_exit.json` - `kit.json` ### Global files - `ai_config.json`: Google AI + optional sidecar settings - `ai_logger.json`: AI/event logging providers and routing - `discord_bridge.json`: Discord interaction bridge server config - `webhook.json`: BattleLuck webhook listener config - `special_item.json`: Special item transformation behavior - `kit_grant_rules.json`: Item-to-kit reward rules for craft completion hooks ## AI, Discord, and Webhooks - The Discord bridge is optional and is disabled by default unless `discord_bridge.json` has `enabled: true`. - The AI assistant can run in Gemini-only mode or with sidecar enrichment. - The sidecar client expects an API root that exposes `GET /health` and `POST /api/query/enrich`. - A Superuser chat page URL is not the same thing as a sidecar API base URL. - Stripe-to-Discord relay support lives in the AI sidecar functions and uses `POST /stripe/discord`. ## Snapshot System BattleLuck snapshots player state before mode entry and restores it on clean exit, rollback, or penalty-death recovery. The runtime currently captures and restores: - Position - Health - Blood state - Equipment level values - Inventory items - Derived equipped gear slots - Weapon entries - Ability slot replacements - Passive buff-like abilities - Active buffs Snapshots are persisted under `BepInEx/data/BattleLuck/snapshots/`. ## Build Release build output: - `bin/Release/net6.0/BattleLuck.dll` Typical build command: ```powershell dotnet build BattleLuck.sln -c Release ``` ### Optional: Build directly to server install Set `VRISING_SERVER_ROOT` to your dedicated server path so post-build copy targets resolve cleanly. Example PowerShell session: ```powershell $env:VRISING_SERVER_ROOT = "C:\\Path\\To\\VRisingServer" dotnet build BattleLuck.sln -c Release ``` ## Thunderstore Packaging This repository now includes a Thunderstore `manifest.json` template at the root. Before publishing, ensure your package zip contains: - `BattleLuck.dll` - `manifest.json` - `README.md` - `icon.png` (256x256) - `CHANGELOG.md` (recommended) Follow upload guidance from the V Rising Mod Wiki: - https://wiki.vrisingmods.com/dev/upload_to_thunderstore.html ## Dependencies and Credits BattleLuck depends on: - BepInEx (mod loader) - VampireCommandFramework (command registration and parsing) Please keep dependency attributions and manifest dependency entries aligned with your released build. ## License BattleLuck is licensed under MIT. See `LICENSE`. Third-party dependency and runtime component notices are documented in `THIRD_PARTY_NOTICES.md`, including `VAutomationCore`, `VampireCommandFramework`, `BepInEx`, `Il2CppInterop`, and other referenced components. ## Notes - Building restriction bypass is handled by debug-setting toggles in `BuildingRestrictionController`. - `PlaceTileModelSystemPatch` only re-blocks castle heart placement while free-build is active. - If prefab validation fails, prefer live prefab scanning/export over stale hardcoded GUIDs. # Battleluck. # Battleluck. # Battleluck. ## Flow Actions Flow actions are strings inside `flow_enter.json` / `flow_exit.json`. Syntax: `actionName:key=value|key2=value2` | Action | Notes | | --- | --- | | `ability.reset_slots` | | | `ability.unlock_all` | | | `ability.unlock_school` | | | `buff.clear_all` | | | `disable_pvp` | | | `enable_pvp` | | | `heal` | | | `inventory.clear_kit` | | | `inventory.send` | | | `kit.apply` | | | `kit.apply_armor` | | | `kit.apply_weapons` | | | `level.set_max` | | | `mode.end` | | | `mode.start` | | | `notify` | | | `player.stun` | | | `player.teleport` | | | `send_message` | | | `set_blood` | | | `snapshot.clear_active` | | | `snapshot.mark_active` | | | `snapshot.restore` | | | `snapshot.restore_old` | | | `snapshot.save` | | | `snapshot.save_old` | | | `state.clear_old` | | | `state.clear_zone` | | | `teleport` | | | `visual_disable` | | | `visual_enable` | | ## Flow Actions Flow actions are strings inside `flow_enter.json` / `flow_exit.json`. Syntax: `actionName:key=value|key2=value2` | Action | Notes | | --- | --- | | `ability.reset_slots` | | | `ability.unlock_all` | | | `ability.unlock_school` | | | `buff.clear_all` | | | `disable_pvp` | | | `enable_pvp` | | | `heal` | | | `inventory.clear_kit` | | | `inventory.send` | | | `kit.apply` | | | `kit.apply_armor` | | | `kit.apply_weapons` | | | `level.set_max` | | | `mode.end` | | | `mode.start` | | | `notify` | | | `player.stun` | | | `player.teleport` | | | `send_message` | | | `set_blood` | | | `snapshot.clear_active` | | | `snapshot.mark_active` | | | `snapshot.restore` | | | `snapshot.restore_old` | | | `snapshot.save` | | | `snapshot.save_old` | | | `state.clear_old` | | | `state.clear_zone` | | | `teleport` | | | `visual_disable` | | | `visual_enable` | | ## Flow Actions Flow actions are strings inside `flow_enter.json` / `flow_exit.json`. Syntax: `actionName:key=value|key2=value2` | Action | Notes | | --- | --- | | `ability.reset_slots` | | | `ability.unlock_all` | | | `ability.unlock_school` | | | `buff.clear_all` | | | `disable_pvp` | | | `enable_pvp` | | | `heal` | | | `inventory.clear_kit` | | | `inventory.send` | | | `kit.apply` | | | `kit.apply_armor` | | | `kit.apply_weapons` | | | `level.set_max` | | | `mode.end` | | | `mode.start` | | | `notify` | | | `player.stun` | | | `player.teleport` | | | `send_message` | | | `set_blood` | | | `snapshot.clear_active` | | | `snapshot.mark_active` | | | `snapshot.restore` | | | `snapshot.restore_old` | | | `snapshot.save` | | | `snapshot.save_old` | | | `state.clear_old` | | | `state.clear_zone` | | | `teleport` | | | `visual_disable` | | | `visual_enable` | |