feat(dungeons): instanced underworld dungeon portal and keystone attunement engine

[angelTomo9]

Summary

Implements an instanced underworld dungeon portal and keystone attunement engine for OpenAO MMORPG.

Features

• Dungeon difficulty tiers (Normal, Heroic, Mythic Keystone)
• Party member level and attunement key requirements
• Dynamic instance expiration timers and auto-collapse
• Boss chamber lockouts and encounter tracking
• Time-scaled reward chest distribution (Bronze, Silver, Gold, Mythic Cache)
• Full unit test coverage under Vitest

[gitar-bot]

Code Review ✅ Approved 3 resolved / 3 findings

Implements instanced underworld dungeon portal and keystone attunement engine with difficulty tiers, party requirements, dynamic timers, boss lockouts, and scaled rewards. Fixes deduplicate party members, applies keystone level timer scaling, and enforces boss chamber lockout on DEFEAT_BOSS.

✅ 3 resolved

✅ Edge Case: Duplicate party members counted but not deduplicated

📄 api/src/lib/underworldDungeonPortal.ts:85-88 📄 api/src/lib/underworldDungeonPortal.ts:105
allMembers only filters out the leader's id from party; it does not deduplicate members that appear twice in party. A malformed party containing the same playerId more than once produces duplicate entries in instance.partyMembers and can trip the maxPartySize check with phantom players. Deduplicate by playerId (e.g. build a Map keyed on playerId) before the size and level checks.

✅ Quality: keystone.levelModifier is defined but never used

📄 api/src/lib/underworldDungeonPortal.ts:23 📄 api/src/lib/underworldDungeonPortal.ts:99-113 📄 api/src/lib/underworldDungeonPortal.ts:177-184
KeystoneItem.levelModifier (documented as +2 to +15) is never read anywhere in openPortal, recordBossEncounter, or determineRewardChest, so keystone level scaling has no effect on instance duration, difficulty, or rewards despite being a core Mythic Keystone concept. Either apply it (e.g. scale durationMs or reward thresholds) or remove the field to avoid implying behavior that does not exist.

✅ Bug: Boss chamber lockout is never enforced on DEFEAT_BOSS

📄 api/src/lib/underworldDungeonPortal.ts:138-152
LOCK_CHAMBER sets isBossChamberLocked = true, but the DEFEAT_BOSS branch never checks that flag before incrementing defeatedBosses — it simply resets the lock to false. This means the lockout has no effect: a boss can be defeated while the chamber is supposedly locked, so the feature described in the PR ("boss chamber lockouts") is inert. If a locked chamber should block progress, add a guard at the start of the DEFEAT_BOSS branch that returns { success: false, ... } when instance.isBossChamberLocked is true.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

---

Important

Your trial ends in 5 days — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

_{Was this helpful? React with 👍 / 👎 | Gitar}