> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/plugins/stressbotplugin.md). # StressBotPlugin Server stress testing plugin that spawns configurable numbers of fake player bots with randomized equipment to test viewport performance, rendering systems, and server load under heavy player density. ## File Location `Data/Plugins/World/StressBotPlugin.xml` ## Dependencies | Depends On | Purpose | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [Item.xml / Item.txt](/docs/data/item/item.md) | Equipment pool source for random bot equipment (items with a slot assignment are added to the pool) | ## Overview StressBotPlugin creates "stress bots" - fake players that appear in the game world with fully randomized equipment and character classes. These bots are visible to real players and generate all the same viewport packets, rendering effects, and server processing as real players, making them ideal for: * Testing server performance under high player density * Stress testing viewport packet processing * Testing client rendering performance with many players * Validating equipment visual effects at scale * Performance profiling under realistic load ## GM Commands All commands require GM authority level 2 or higher (admin/GM). | Command | Description | | -------------------------------- | --------------------------------------- | | `/stressbot spawn ` | Spawn specified number of bots on a map | | `/stressbot clear ` | Remove all bots from specified map | | `/stressbot clearall` | Remove all bots from all maps | | `/stressbot status` | Display current bot counts per map | | `/stressbot reload` | Reload configuration from XML | ### Command Examples ``` /stressbot spawn 0 100 - Spawn 100 bots in Lorencia /stressbot spawn 2 50 - Spawn 50 bots in Devias /stressbot clear 0 - Remove all bots from Lorencia /stressbot clearall - Remove all bots from all maps /stressbot status - Show current bot distribution ``` ## Configuration Attributes ### Core Settings | Attribute | Type | Default | Description | | --------- | ---- | ------- | ---------------------------------------------------------------------------- | | `Enabled` | bool | false | Enable/disable the plugin. Set to `true` to activate stress testing features | ### Bot Limits | Attribute | Type | Default | Description | | --------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MaxBotsPerMap` | int | 200 | Maximum number of bots allowed per map. Higher values create more concentrated stress. Limited by server memory. | | `MaxBotsTotal` | int | 500 | Maximum total bots across all maps. Bots consume slots from the shared summon-object pool (also used by player pets, guardians, and other summoned objects). | ### Bot Appearance | Attribute | Type | Default | Description | | ----------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DefaultBotLevel` | int | 400 | Level assigned to spawned bots. Affects visual appearance through armor glow effects and animations. Higher levels display more advanced visual effects | | `DefaultBotClass` | int | 1 | Default character class when `RandomizeClass="false"`. Values: 0=Dark Wizard, 1=Dark Knight, 2=Fairy Elf, 3=Magic Gladiator, 4=Dark Lord, 5=Summoner, 6=Rage Fighter | | `RandomizeClass` | bool | true | If true, each bot receives a random class (0-6). Creates visual variety for more realistic testing scenarios | ### Equipment Settings | Attribute | Type | Default | Description | | -------------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `RandomizeEquipment` | bool | true | If true, equips bots with random items from Item.xml. Tests equipment rendering, glow effects, and visual system performance | | `RandomizeWings` | bool | true | If true, includes wings in equipment randomization. Wings have high-impact particle effects and should be tested separately | | `ItemLevel` | int | 13 | Item level for equipped items (0-15). Higher levels = more visual effects (glow, particles). Level 13+ creates significant visual complexity | | `ItemOption` | int | 16 | Additional option level (+4, +8, +12, +16). Value represents the actual bonus. Adds stat display effects and visual indicators | | `ItemExcellent` | bool | true | Add excellent options to items. Excellent items have special glow effects and are the most visually intensive item type | ### Spawn Behavior | Attribute | Type | Default | Description | | -------------------- | ---- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WalkableRetryCount` | int | 50 | Number of random position attempts before fallback. Higher values = better spatial distribution but slower spawn time. 50 is typically sufficient for most maps | ## Important Behavior {% hint style="info" %} **Bot Spawning Algorithm**: Bots attempt to spawn near the GM who issued the spawn command (within 15 tile radius). If no walkable position is found nearby, the system falls back to random map positions, and finally to the map center area (coordinates 100-156). {% endhint %} {% hint style="warning" %} **Memory Usage**: Each bot consumes the full OBJECTSTRUCT plus inventory and equipment arrays. Plan on tens of MB per thousand bots and monitor server RSS during testing. {% endhint %} {% hint style="warning" %} **Viewport Complexity**: Viewport updates are O(n^2) complexity. Each player sees all nearby players, so 100 bots in one area generates 10,000 viewport update calculations. Start with 50-100 bots and increase gradually. {% endhint %} {% hint style="info" %} **Item Pool Loading**: The plugin reads Item.xml on initialization and builds separate pools for regular equipment (slots 0-6) and wings (slot 7). Only items with valid slot assignments are included in randomization. {% endhint %} {% hint style="info" %} **Bot Safety**: Bots are configured with extremely high Life (30,000), Defense (32,000), and MagicDefense (32,000) to prevent death during testing. Bot death can cause server crashes as they don't have full player cleanup handlers. {% endhint %} {% hint style="warning" %} **Cleanup Required**: Always use `/stressbot clearall` when finished testing. Leaving bots active consumes summon slots that would normally be available for players' pets and summons. {% endhint %} ## Common Map Numbers | Map ID | Map Name | Map ID | Map Name | | ------ | ---------- | ------ | ----------------- | | 0 | Lorencia | 30 | Castle Siege | | 1 | Dungeon | 31 | Land of Trials | | 2 | Devias | 33 | Aida | | 3 | Noria | 34 | Crywolf | | 4 | Lost Tower | 51 | Elbeland | | 7 | Atlans | 56 | Swamp of Calmness | | 8 | Tarkan | 57 | Raklion | | 10 | Icarus | | | ## Examples {% tabs %} {% tab title="Development Testing" %} ```xml ``` Conservative settings for development testing. 100 bots per map, full equipment randomization for visual testing. {% endtab %} {% tab title="High Stress Test" %} ```xml ``` Maximum stress configuration. 1000 bots with maximum item levels (15) and all visual effects enabled. Use for load testing and performance profiling. **Monitor server CPU/memory closely**. {% endtab %} {% tab title="Uniform Testing" %} ```xml ``` All bots are identical Dark Knights with no equipment. Useful for isolating viewport packet performance without equipment rendering overhead. {% endtab %} {% tab title="Wings Only Test" %} ```xml ``` Tests only wing rendering performance. Bots wear no armor but have random wings with maximum visual effects. Isolates wing particle system performance. {% endtab %} {% endtabs %} ## Performance Testing Workflow ### 1. Baseline Test ``` /stressbot spawn 0 50 ``` Start with 50 bots in Lorencia. Check server CPU, memory, and client FPS. ### 2. Incremental Load ``` /stressbot spawn 0 50 (50 total) /stressbot spawn 0 50 (100 total) /stressbot spawn 0 50 (150 total) ``` Incrementally add bots to find performance thresholds. ### 3. Multi-Map Distribution ``` /stressbot spawn 0 100 (Lorencia) /stressbot spawn 2 100 (Devias) /stressbot spawn 3 100 (Noria) ``` Test server performance with load distributed across multiple maps. ### 4. Status Monitoring ``` /stressbot status ``` Regularly check bot distribution and ensure limits aren't exceeded. ### 5. Cleanup ``` /stressbot clearall ``` **Always** clear bots when testing is complete to free server resources. ## Common Issues {% hint style="warning" %} **Issue**: Bots fail to spawn (message shows "X failed") **Causes**: * Map has limited walkable space (increase `WalkableRetryCount`) * Summon object pool exhausted (clear existing bots or reduce `MaxBotsTotal`) * Invalid map number (check Map ID table) **Solution**: Use `/stressbot status` to check current bot count, clear existing bots, or try a different map with more open space. {% endhint %} {% hint style="warning" %} **Issue**: Server performance degrades severely **Causes**: * Too many bots in one viewport area (O(n^2) packet processing) * High ItemLevel/Excellent items creating excessive particle effects * Client machine limitations (not server issue) **Solution**: Reduce bot count, disable equipment randomization, or distribute bots across multiple maps. Monitor both server CPU and client FPS separately. {% endhint %} {% hint style="warning" %} **Issue**: Bots disappear after server restart **Behavior**: This is **expected**. Stress bots are not saved to the database. They exist only in server memory and are cleared on restart. **Solution**: Re-spawn bots after restart using `/stressbot spawn` commands. {% endhint %} {% hint style="warning" %} **Issue**: Cannot spawn more bots despite being under limits **Cause**: The summon-object pool is shared with player pets, guardians, and other summons. When the pool is exhausted, `gObjAddSummon` fails and the bot spawn aborts. **Solution**: Clear existing bots (`/stressbot clearall`), or ask players to unsummon pets/guardians temporarily. Check active bot count with `/stressbot status`. {% endhint %} {% hint style="info" %} **Tip**: For viewport stress testing, spawn all bots in a small area (they spawn near the GM). For distributed load testing, teleport to different locations before each `/stressbot spawn` command. {% endhint %} ## Technical Details ### Bot Properties Stress bots are configured as follows: * **Type**: `OBJECT_BOTS` (appears in viewport, minimal server processing) * **Life/Mana**: 30,000 (prevents death) * **Defense**: 32,000 (monsters cannot damage them) * **MagicDefense**: 32,000 (magic attacks cannot damage them) * **Level**: Configurable (affects visual appearance) * **Name**: `Bot#####` where ##### is object index (e.g., "Bot15450") * **Inventory**: Full inventory array allocated (equipment plus inventory and InventoryMap arrays) * **Movement**: Stationary (no AI, no walking) * **Combat**: Cannot attack, cannot be killed ### Slot Assignment Equipment slots match MU Online's standard layout: | Slot | Name | Slot | Name | | ---- | -------------- | ---- | ------ | | 0 | Weapon (Right) | 5 | Gloves | | 1 | Weapon (Left) | 6 | Boots | | 2 | Helm | 7 | Wings | | 3 | Armor | 8 | Pet | | 4 | Pants | | | When `RandomizeEquipment="true"`, slots 0-6 are filled with random items from the Item.xml pool that match each slot. Wings (slot 7) are only equipped if `RandomizeWings="true"`. ### Item Excellent Options When `ItemExcellent="true"`, bots receive `0x3F` (all 6 excellent options): * Excellent items display special glow effects * This creates maximum visual complexity for stress testing * Performance impact is significant with 100+ bots Set to `false` for baseline testing without excellent effects.