Twin Emperors: implement pre-pull staging, opener, and teleport-ready raid positioning

[RovxBot]

Objective

Implement a deterministic Twin Emperors pre-pull setup and opener so the raid splits into the correct room positions before pull, starts the fight from the right formation, and pre-stages for teleports before the swap actually lands.

Why this exists

The existing Twin issue set covered the collapse after pull, but did not spell out the opener choreography tightly enough for an implementing agent.

Your intended encounter contract is more specific than the current code:

• as the raid enters the room and reaches the center, bots should split into pre-pull spots instead of loosely collapsing
• each side should have 1 warlock tank and 1 melee tank
• the main tank should always start on Vek'nilash's initial side
• each side should have 2 dedicated tank healers
• remaining healers and ranged DPS should spread out from the middle and be ready to move on pull
• melee DPS should engage Vek'nilash on pull
• melee DPS should rotate early toward the receiving side before teleport so they are ready when Vek'nilash arrives

Current code baseline

There is already partial support for staging, but it is not enough:

• src/Ai/Raid/Aq40/Action/RaidAq40Actions_TwinEmperors.cpp
  • Aq40TwinEmperorsPrePullStageAction already stages:
    • warlock tanks to a side-specific anchor
    • melee tanks to a side anchor
    • dedicated tank healers to side healer anchors
    • everyone else to the exact room center
• src/Ai/Raid/Aq40/Multiplier/RaidAq40Multipliers.cpp
  • Aq40TwinEmperorsMultiplier already gives staging full movement ownership during pre-pull
• src/Ai/Raid/Aq40/Util/RaidAq40Helpers.cpp
  • GetStableTwinRoleIndex already prefers:
    • warlocks on initial Vek'lor side first
    • melee tanks on initial Vek'nilash side first
  • kTwinTankHealersPerSide = 2 already exists

This means the structure is present, but the current behavior is still too simple:

• non-tank, non-dedicated-healer bots collapse to one exact center point instead of a usable spread
• the opener does not explicitly encode melee DPS opening on Vek'nilash
• the raid is not explicitly staged for the next teleport before it happens

Required implementation

Pre-pull split

• When the raid reaches the Twin room center and pre-pull staging activates, split the raid into deterministic staging positions before pull.
• Supported pre-pull side composition must be:
  • Vek'nilash side: 1 melee tank, 1 warlock tank, 2 dedicated tank healers
  • opposite side: 1 melee tank, 1 warlock tank, 2 dedicated tank healers
• The main tank must always start on Vek'nilash's initial side.
• Reserve / backup tanks may have parked anchors, but must not contaminate the active pre-pull pickup geometry.
• Tanks should be staged to pull the emperors off their pedestals into floor-level side positions that keep the bosses far apart and compatible with the later split geometry.

Center-spread opener layout

• Remaining healers and ranged DPS must not all stand on one exact center point.
• Replace the current exact-center collapse with a deterministic center-spread layout:
  • fixed slots, arcs, or a small anchor family are all acceptable
  • the main requirement is that they begin near the center while not overstacking and while keeping room to transition cleanly on pull
• Non-dedicated healers should remain central in pre-pull unless explicitly assigned otherwise.
• Dedicated tank healers may stage closer to the entrance-stair / side-healer area nearest their tank, rather than behaving like generic center healers.

Fight start behavior

• On pull:
  • melee DPS should move in and attack Vek'nilash
  • caster ranged DPS should remain in intended central / Vek'lor-safe opening positions
  • dedicated side healers should already be on their side assignments and should not need to re-solve their opener from the center
• The opener should not rely on generic follow/assist logic once Twin staging owns movement.

Teleport-ready raid positioning

• Before the teleport lands, melee DPS should move early toward the receiving side so they are ready when Vek'nilash arrives.
• Use the encounter's teleport timing model for this rather than waiting until after the swap resolves.
• Current code already arms kTwinTeleportWindowMs = 6000; this issue should either use that window directly or define a narrower pre-teleport movement sub-window inside it.
• Melee DPS repositioning must respect tank pickup space and must not block the designated receiving tank geometry.
• Damage dealers still must not be the nearest valid pickup units when teleport resolves.

Code hotspots

• src/Ai/Raid/Aq40/Action/RaidAq40Actions_TwinEmperors.cpp
  • Aq40TwinEmperorsPrePullStageAction
  • Aq40TwinEmperorsChooseTargetAction
  • GetTwinCentralWaitAnchor
  • GetTwinSideAnchor
  • GetTwinSideHealerAnchor
• src/Ai/Raid/Aq40/Util/RaidAq40Helpers.cpp
  • GetStableTwinRoleIndex
  • GetTwinDedicatedTankHealerSide
  • staged side / role lock helpers
• src/Ai/Raid/Aq40/Multiplier/RaidAq40Multipliers.cpp
  • pre-pull movement suppression and opener ownership
• src/Ai/Raid/Aq40/Util/RaidAq40TwinEmperors.cpp
  • teleport window timing state

Reference patterns

• Sunwell Eredar Twins positioning:
  • https://github.com/brighton-chi/mod-playerbots/blob/the-lab/src/Ai/Raid/SunwellPlateau/Action/RaidSunwellEredarTwinsActions.cpp
  • Relevant patterns:
    • fixed ranged positions
    • forced stack / waiting positions
    • encounter-owned movement instead of generic formation logic
• PR #2258: Implement Battle for Mount Hyjal Strategies mod-playerbots/mod-playerbots#2258
  • Useful precedent for deterministic ranged spreads and encounter-owned opener positions.
• PR #2363: ICC V2, Autogear BiS cmd mod-playerbots/mod-playerbots#2363
  • Gold-standard expectation for stable, deterministic raid strategy behavior and strict movement ownership.

Validation

• Pre-pull test:
  • run into the Twin room without pulling
  • verify the raid splits into staging positions automatically when reaching the room center
  • verify side composition matches the intended opener contract
• Pull test:
  • verify melee DPS open on Vek'nilash
  • verify dedicated tank healers are already on their side assignments at pull start
  • verify remaining healers / ranged are spread from the middle rather than stacked on one exact point
• First teleport test:
  • verify melee DPS move early toward the receiving side before teleport lands
  • verify melee movement does not interfere with tank pickup anchors
  • verify damage dealers are not stealing nearest-player pickup from tanks at teleport resolution

Acceptance criteria

• Pre-pull staging no longer collapses the raid into one center point except where explicitly intended.
• Main tank always starts on Vek'nilash's initial side in supported runs.
• Each side starts with 1 warlock tank, 1 melee tank, and 2 dedicated tank healers.
• Melee DPS open on Vek'nilash and pre-stage early for teleports without breaking pickup rules.
• Remaining healers and ranged DPS use a stable center-spread opener layout.

Related

• Builds on #2 Twin Emperors: rebuild encounter state machine and stable ownership
• Coordinates with #3 tank teleport-prep geometry
• Coordinates with #4 healer side support and dedicated healer behavior
• Coordinates with #5 ranged positioning and Vek'lor-safe movement
• Coordinates with #9 pull-safety and previous-room Defender gating.