mod-playerbots-wintergrasp

Created by iCore.

License: GNU GPL v2 or later.

A standalone AzerothCore module for mod-playerbots that automatically accepts both Wintergrasp invitations and can optionally run dedicated Wintergrasp objective, workshop, vehicle, and cannon tactics.

Tactics are enabled by default in the distributed configuration and can be disabled independently of invitation acceptance. The maintainer reports that the current version works reasonably well in local gameplay. Complete battles for both factions and measured performance results are not documented; the regression checklist remains in LOCAL_TEST.md.

The current update improves engineer-menu vehicle construction, protects active build casts, keeps infantry available outside the attacker rank squad, and releases unseated cannon claims when ranked defenders are needed to build vehicles. It also includes the existing terrain-descent, fortress-routing, tower-assault, and master-command handling improvements.

What is it designed for?

Target environment:

• https://github.com/mod-playerbots/azerothcore-wotlk — Playerbot branch
• https://github.com/mod-playerbots/mod-playerbots — master

Build together with mod-playerbots using -DMODULES=static because the tactical controller uses the public Playerbot AI classes. Invitation handling needs no SQL. The optional building-damage compatibility fix has a manually applied core patch and WORLD database update, described below.

This module accepts invitations that the core actually sends. It does not recruit bots from other zones or populate Wintergrasp camps. Core/manual queueing or a separate population provider must supply those bots. City Life/PvP Life population data and shared playerbot BG-reservation fixes are external to this repository.

What does it do?

1. It monitors outgoing packets sent to bots through the core's ServerScript::OnPacketSent hook.

2. When the bot receives an SMSG_BATTLEFIELD_MGR_QUEUE_INVITE packet:

   • after a small random delay, it calls the core's own Battlefield::PlayerAcceptInviteToQueue() function.

3. When the bot receives an SMSG_BATTLEFIELD_MGR_ENTRY_INVITE packet:

   • after a small random delay, it calls the core's own Battlefield::PlayerAcceptInviteToWar() function.

4. Before accepting the battle-entry invitation, the module checks whether the bot is actually present in the Wintergrasp server-side invited map.

5. The core itself handles invite expiration, adds the bot to the raid group, and sends the entered response.

6. With PlayerbotsWintergrasp.Tactics.Enable = 1, bots that are already enrolled in an active Wintergrasp battle use dedicated logic for:

   • A* routes and battlefield objectives
   • Workshop capture and ownership changes
   • Vehicle summoning and boarding
   • Attacker wall/gate pressure and defender tower pressure
   • Fortress cannon boarding and vehicle weapon targeting

7. With PlayerbotsWintergrasp.GraveyardRespawn.Enable = 1, a dead bot releases normally to its closest friendly Wintergrasp graveyard, waits beside the spirit healer, and joins the next battlefield resurrection wave instead of running back to its corpse.

8. Every non-falling bot spline in the Wintergrasp zone is checked against standing fortress barriers and the complete static and dynamic collision trees. PATHFIND_SHORTCUT is rejected for tactical movement, preventing random, combat, RPG, or follow movement from walking through active walls, doors, and workshop objects.

9. Bots with a real-player or selfbot master receive autonomous WG objectives while idle. Master follow, stay, runaway, and combat commands always take movement priority. The follow assist runs for enrolled bots during an active Wintergrasp battle, safely searches several landing directions after a downward jump, and replaces wall-crossing follow splines with guarded A* routes. Master jump following has a three-second hold; sampled terrain descents have a separate fifteen-second timeout and yield between controller ticks.

10. Autonomous attackers maintain a rank-farming group until the configured minimum vehicle count is reached. Its configured size is an upper limit, capped at roughly 30% of available infantry so workshop duties retain bots. Recruits sweep reachable guards at the gate and side-conflict checkpoints. Promoted bots travel to controlled outer workshops, build siege engines, and assault the fortress walls, central wall, and vault door.

11. Defender workshop capture runs before fortress vehicle duty, so promoted defenders no longer all collect inside the keep. Controlling an outer workshop also controls its associated graveyard.

12. Defender vehicles retain a small configurable fortress guard, then form configurable squads to destroy the attacker's three southern towers. In standard Wintergrasp rules those towers belong to the attacking team; the attackers defend them while pushing the fortress.

13. Defender infantry outside a closed fortress finds, approaches, and uses a live Defender's Portal (entry 190763) when its objective is inside. The live BattlefieldWG owner is checked before every use, so attackers can never receive the portal action. Fortress-exit routing follows an authored exit and jumps from its exterior endpoint when a complete outward route is unavailable. General terrain descents use the separate checks below.

14. An mmap shortcut remains forbidden for random, combat, RPG, and direct master movement. A single hand-authored WG graph edge may use it only after the whole segment passes standing-wall plus static/dynamic collision checks; this lets defenders leave the elevated fortress respawn route without reopening wall walking.

15. Autonomous infantry and assisted followers can also step down from terrain and graveyard ledges anywhere in WG. They sample nearby ground before consulting the A* blocked-route cache, then follow a short descent spline without asking the navmesh to reconnect the edge. The search covers nine directions, up to 32 yards horizontally and 60 yards down, and also works when the final objective is higher across a valley. Every segment retains standing wall and world-collision checks. Dead bots still wait for resurrection; vehicles, flying, swimming, rooted, and controlled bots do not start a terrain descent. This is automatic and needs no new command or config option.

16. While a southern tower still stands, defender rank duty keeps the configured central recruit squad replenished outside fortress emergencies, even when the minimum vehicle count is already satisfied. Rankless infantry at Eastspark joins the nearby SE tower guard sweep directly, without taking slots away from that central squad. Promotion and vehicle boarding release recruit slots before higher-priority controller actions can bypass infantry logic. The sweep approaches road points outside the South/SE tower models, finds reachable live rank-credit NPCs, and starts the normal playerbot attack action instead of merely selecting a target. Empty guard areas advance to the next checkpoint, so rankless bots keep searching instead of waiting for rank at the workshop.

17. An assigned defender vehicle assault continues onto the remaining southern towers even when their initial squad caps are full. Once all three are destroyed, the surviving vehicles return to the fortress before resuming guard or anti-siege duty, and the tower-preparation recruit sweep ends. Tower movement and building fire take priority over generic vehicle shots; vehicles approach a checked firing position outside the tower and finish moving before casting. The configured emergency recall remains available.

18. Building shots use an exact destination and a projectile arc that accounts for the height difference. Projectile weapons are tried before Ram; each update starts at most one successful cast, respects cooldowns and active casts, and checks Ram against the building's actual effect-radius intersection. Spell preparation failures are not counted as successful shots. Damage and projectile collision still run through the core's normal spell handling.

19. Vehicle construction uses the workshop engineer's live gossip menu. Bots stop before the normal build cast and protect it for at most ten seconds, with a two-second retry delay. Attackers require First Lieutenant for Siege Engines; defenders can build Catapults at Corporal and Demolishers at First Lieutenant. Ranked defenders release unseated cannon claims while their team needs mobile vehicles.

The tactics controller never creates or accepts an invitation. It starts only after Battlefield::IsPlayerInBattlefield() confirms that the existing invitation path enrolled the bot.

Why doesn't it accept the invitation directly from the packet hook?

Outgoing Playerbot packet processing can run from multiple threads. Therefore, the module only creates a mutex-protected "pending accept" entry in the packet hook.

The actual Battlefield state changes and raid-group modifications are performed from the WorldScript::OnUpdate hook on the world thread.

This matches the execution context used by the Core's PROCESS_THREADUNSAFE Battlefield packet handlers.

Installation

Copy the entire module directory here:

azerothcore-wotlk/
└── modules/
    ├── mod-playerbots/
    └── mod-playerbots-wintergrasp/

Important: the directory name must be exactly:

mod-playerbots-wintergrasp

The loader name is based on this directory name:

Addmod_playerbots_wintergraspScripts()

After that, CMake must be reconfigured, and the core must be rebuilt.

Example on Linux (static modules are required for the tactics port):

cd azerothcore-wotlk/build
cmake .. -DMODULES=static
make -j$(nproc)
make install

Windows / Visual Studio

1. CMake Configure
2. CMake Generate
3. Build ALL_BUILD
4. Copy/install the updated worldserver using your usual procedure.

Configuration

The module provides:

conf/mod_playerbots_wintergrasp.conf.dist

After building/installing, create an active .conf file in the module's configuration directory:

mod_playerbots_wintergrasp.conf

Recommended initial test configuration:

PlayerbotsWintergrasp.Enable = 1
PlayerbotsWintergrasp.AcceptQueue = 1
PlayerbotsWintergrasp.AcceptBattle = 1
PlayerbotsWintergrasp.Announce = 1
PlayerbotsWintergrasp.AcceptDelayMin = 500
PlayerbotsWintergrasp.AcceptDelayMax = 2500
PlayerbotsWintergrasp.TeamBalance.MaxDifference = 1
PlayerbotsWintergrasp.Tactics.Enable = 1
PlayerbotsWintergrasp.Tactics.PlayerOwnedBots = 1
PlayerbotsWintergrasp.Tactics.FortressGhostExit = 0
PlayerbotsWintergrasp.MasterFollowAssist.Enable = 1
PlayerbotsWintergrasp.Tactics.UpdateInterval = 1000
PlayerbotsWintergrasp.Tactics.AttackerMinVehicles = 4
PlayerbotsWintergrasp.Tactics.AttackerRankSquadSize = 20
PlayerbotsWintergrasp.Tactics.AttackerCaptureSquadSize = 0
PlayerbotsWintergrasp.Tactics.DefenderMinVehicles = 5
PlayerbotsWintergrasp.Tactics.DefenderRankSquadSize = 16
PlayerbotsWintergrasp.Tactics.DefenderCaptureSquadSize = 14
PlayerbotsWintergrasp.Tactics.DefenderCannonSquadSize = 6
PlayerbotsWintergrasp.Tactics.DefenderFortressInfantrySquadSize = 10
PlayerbotsWintergrasp.Tactics.DefenderEmergencyInfantrySquadSize = 32
PlayerbotsWintergrasp.Tactics.DefenderEmergencyVehicleRange = 220
PlayerbotsWintergrasp.Tactics.DefenderEmergencyRecallTowerVehicles = 0
PlayerbotsWintergrasp.Tactics.DefenderPriorityBrokenSunken = 1
PlayerbotsWintergrasp.Tactics.DefenderFortGuardPerPosition = 2
PlayerbotsWintergrasp.Tactics.DefenderTowerVehicleSquad = 2
PlayerbotsWintergrasp.Tactics.DefenderTowerAttackers = 4
PlayerbotsWintergrasp.GraveyardRespawn.Enable = 1
PlayerbotsWintergrasp.Debug = 1

To isolate invitation handling, temporarily set PlayerbotsWintergrasp.Tactics.Enable = 0. Restore the default tactical controller afterward with:

PlayerbotsWintergrasp.Tactics.Enable = 1

Once everything is working:

PlayerbotsWintergrasp.Debug = 0

Testing

1. Start the worldserver.
2. You should see the following in the console:

>> Loaded mod-playerbots-wintergrasp

3. Have a playerbot in Wintergrasp at a time when the WG queue call appears.
4. With Debug = 1, you should see messages similar to:

[PlayerbotsWintergrasp] BotName: Wintergrasp queue invite detected, accepting in 1234 ms
[PlayerbotsWintergrasp] BotName: accepted Wintergrasp queue invite

When a real player enters the game, if Announce is enabled:

mod-playerbots-wintergrasp module created by iCore.

When the battle starts:

[PlayerbotsWintergrasp] BotName: Wintergrasp battle-entry invite detected, accepting in 987 ms
[PlayerbotsWintergrasp] BotName: accepted Wintergrasp battle-entry invite

The current Battlefield core in the Playerbot fork also provides the .bf queue command for checking the queue / invited / in-war state, if that command is available in your build.

Local tactics test checklist

The current local build provides:

• Queue call acceptance: yes, unchanged
• Enter Battle acceptance: yes, unchanged
• Joining the WG raid: yes, through the normal Core path
• Invite expiration checking: yes, handled by the Core
• Dedicated Wintergrasp objective AI: experimental
• Workshop / vehicle / wall / tower strategy: experimental
• Graveyard spirit-healer resurrection instead of corpse running: yes, enabled by default
• Dynamic Wintergrasp game-object collision avoidance: yes
• Real-player master commands take priority over autonomous WG tactics: yes
• Configurable attacker rank squad and minimum vehicle target: yes
• Defender workshop/graveyard counter-capture priority: yes
• Defender vehicle squads for all three southern attacker towers: yes
• Owner-only defender portal entry and authored emergency exit routing: yes, requires live testing

During a test battle, check both factions and watch for these milestones:

1. Bots still accept queue and entry invitations with the configured randomized delay.
2. No tactical movement starts before the bot is listed as in-war.
3. Infantry spreads between objectives and contests capturable workshops.
4. Lieutenant-ranked bots summon and board vehicles when slots are available.
5. Attacker vehicles damage the fortress and defender vehicles pressure southern towers.
6. Defenders near the fortress board free cannons and fire at hostile vehicles.
7. After death, bots remain at their friendly graveyard and resurrect with the next Wintergrasp spirit-healer wave.
8. Logout, battle end, and config reload release the bot's tactical assignment.
9. Infantry and vehicles route around intact workshop buildings and other dynamic game objects.
10. With Tactics.PlayerOwnedBots = 1, a player-owned bot receives an autonomous attacker or defender assignment while idle, but immediately yields movement to follow/stay/combat commands and safely follows nearby downward jumps.
11. While attackers have fewer than the configured vehicle minimum, the effective capped rank squad sweeps the central and side approaches and shares nearby guard/player kill credit.
12. Promoted attackers repeatedly replace destroyed vehicles and drive them against the fortress, while other attackers continue taking outer workshops.
13. Defenders contest hostile workshops and their linked graveyards instead of concentrating entirely inside the keep.
14. After the small fortress guard is filled, defender vehicles leave the keep and destroy all three southern towers.
15. A defender outside the intact fortress uses entry 190763 to enter; an attacker never attempts to use it.
16. With Tactics.FortressGhostExit = 0, a defender with no complete outside route uses the authored fortress exits.
17. With Tactics.FortressGhostExit = 1, a defender whose objective is outside may leave directly through fortress geometry; the exception is outbound-only and never permits outside-to-inside clipping.

Optional building-damage compatibility fix

Invitation handling does not require database modifications. For cores that need the vehicle building-target correction, this repository includes a manual companion patch and WORLD SQL update. Neither is applied automatically. They cover vehicle building targeting, rotated model-range geometry for Ram hits, and the Siege Engine Ram, Demolisher Ram/Boulder, and Catapult Plague Barrel spell bindings. The patch touches BattlefieldWG.h, GameObject.cpp, and zone_wintergrasp.cpp. Its inverse-rotation correction affects the shared GameObject::IsInRange2d/IsInRange3d helpers, so review it against your core before applying. It does not require NoxMax's extra query methods or install City Life/PvP Life population data or shared BG-reservation changes.

From the core repository root, with this module at modules/mod-playerbots-wintergrasp, check and apply:

git apply --check modules/mod-playerbots-wintergrasp/patches/core-wintergrasp-building-targets.patch
git apply modules/mod-playerbots-wintergrasp/patches/core-wintergrasp-building-targets.patch

Rebuild and install the core with static modules using the build procedure above. Import the companion SQL into your WORLD database, replacing the example account and database names:

mysql --user=YOUR_DB_USER --password YOUR_WORLD_DATABASE < modules/mod-playerbots-wintergrasp/data/sql/updates/pending_db_world/rev_1789888733824787200.sql

On Windows, the same file can be imported from the MySQL client started in the core root with the WORLD database selected:

SOURCE modules/mod-playerbots-wintergrasp/data/sql/updates/pending_db_world/rev_1789888733824787200.sql;

The SQL is idempotent. If the earlier three-spell version was applied, importing this version also adds the Siege Engine Ram and Plague Barrel impact bindings. Run the updated executable to use the changed core code.

Compatibility Notes

This source targets the Playerbot fork and its mod-playerbots APIs, including the outgoing-packet hook, world-update/config hooks, Battlefield queue/invite accessors, and playerbot movement and spell helpers. It is not intended for standard upstream AzerothCore. Build the two projects together with static modules.

The local integration source uses core base 2a2211cd8f3d157da432ec0175ddd4b8a191931f and playerbots base 77650b3ad4df720d5ae556c73f43deeb35469492, with local changes. These identify the integration baseline, not a claim that every revision of the public branches or every test case has been validated.

Attribution

The original Wintergrasp bot concept and foundation come from NoxMax's GPL-2.0-or-later work:

• NoxMax/mod-playerbots, branch The-Winds-of-Wintergrasp
• NoxMax/azerothcore-wotlk, branch Nox-AC-PB-WG

The implementation included in this module has since been revised and improved.

This module replaces the two extra BattlefieldWG query methods from that core branch with a module-owned cache of authoritative world-state packets, so those query-method core changes are unnecessary. The optional building-damage companion above is a separate core/SQL compatibility fix.

Match balance and defender tactical squads

Tactical fixes and deployment

Mobile vehicles now navigate before generic combat actions. Building attacks accept a controlling driver seat, follow missile spells through to their building-damage impact, and check Ram against the building model instead of only its origin. This covers Siege Engine Ram, Demolisher Ram/Boulder, and Catapult Plague Barrel. The module's manual companion patch and SQL in the building-damage section provide the associated core targeting and spell bindings when required by the installed core.

Follow routing no longer refreshes a global AI delay on every update. Combat and master commands keep running. Unreachable hostile sightings yield back to travel rather than holding the bot indefinitely. Fortress infantry actively acquires nearby hostile vehicles, and threatened or breached sides receive a larger defense allocation. Autonomous infantry in a raid subgroup shares workshop choices and closes on nearby squadmates along checked paths. Rank, capture, cannon, and fortress infantry limits are additionally capped at 30%, 30%, 10%, and 20% of available defender infantry respectively, so small battles retain multiple roles. Each enabled role can keep at least one bot.

Fortress cannon approaches reserve their seat. An approach that fails for 45 seconds releases the claim and avoids that cannon for 60 seconds. Nearby autonomous infantry can also board an unoccupied turret on a driven Siege Engine. Bots persistently detected below a nearby surface for two seconds recover vertically; valid lower floors, falling, swimming, flying, vehicles, and combat are excluded. Keep Tactics.FortressGhostExit = 0 to use checked exits.

Build and install the updated executable before testing. An older worldserver.exe in the server directory still runs the old behavior even if the source and build output have changed. Test both attacker factions: all three southern towers, fortress gate/side walls, cannon and siege turret boarding, defense against vehicles, distant follow, summon while following, and normal bridge/fortress movement.

Bot entry is kept within the configured team-size difference. A bot with a valid invite waits briefly when accepting it would make its side too large; real players are never delayed by the module:

PlayerbotsWintergrasp.TeamBalance.MaxDifference = 1
PlayerbotsWintergrasp.TeamBalance.Rebalance.Enable = 1
PlayerbotsWintergrasp.TeamBalance.Rebalance.Delay = 30000

The ongoing balance check waits for the configured delay in milliseconds before removing an idle autonomous random bot from the larger team. Further removals are at least five seconds apart until the permitted difference is restored. It preserves real players, player-controlled bots, active combat, and vehicle crews; when every excess participant is protected it waits. A zero maximum difference is clamped to one to permit sequential entry.

The attacker and defender economies can be tuned independently. Attackers keep their adaptive capture/push flow, while defenders have dedicated vehicle, capture, cannon and fortress-defense roles:

PlayerbotsWintergrasp.Tactics.AttackerMinVehicles = 4
PlayerbotsWintergrasp.Tactics.AttackerRankSquadSize = 20
PlayerbotsWintergrasp.Tactics.AttackerCaptureSquadSize = 0

PlayerbotsWintergrasp.Tactics.DefenderMinVehicles = 5
PlayerbotsWintergrasp.Tactics.DefenderRankSquadSize = 16
PlayerbotsWintergrasp.Tactics.DefenderCaptureSquadSize = 14
PlayerbotsWintergrasp.Tactics.DefenderCannonSquadSize = 6
PlayerbotsWintergrasp.Tactics.DefenderFortressInfantrySquadSize = 10
PlayerbotsWintergrasp.Tactics.DefenderEmergencyInfantrySquadSize = 32
PlayerbotsWintergrasp.Tactics.DefenderEmergencyVehicleRange = 220
PlayerbotsWintergrasp.Tactics.DefenderEmergencyRecallTowerVehicles = 0
PlayerbotsWintergrasp.Tactics.DefenderPriorityBrokenSunken = 1
PlayerbotsWintergrasp.Tactics.DefenderFortGuardPerPosition = 2
PlayerbotsWintergrasp.Tactics.DefenderTowerVehicleSquad = 2
PlayerbotsWintergrasp.Tactics.DefenderTowerAttackers = 4

DefenderMinVehicles keeps the defender vehicle pipeline alive until a useful floor exists. The dedicated defender rank squad now runs a tower-counterattack preparation sweep from the central approach through the South Tower guard area, secures Eastspark, and—if rank is still missing—clears the SE Tower guard area. Corporal defenders can build Catapults and First Lieutenants build Demolishers; the tower-prep squad builds at Eastspark and then joins the configured southern tower attack force. DefenderCannonSquadSize reserves gunners for fortress cannons, while DefenderFortressInfantrySquadSize keeps an infantry reserve at the gate/front court. When DefenderPriorityBrokenSunken is enabled, the general defender capture squad still prefers Sunken Ring and Broken Temple. By default tower-attack vehicles are not recalled during fortress emergency defense; this can be changed with DefenderEmergencyRecallTowerVehicles.

AttackerCaptureSquadSize is optional and defaults to zero because the existing adaptive attacker capture logic is already aggressive; it is exposed so both sides can still be tuned from configuration.