MosswartOverlord/docs/plans/2026-01-30-suitbuilder-design.md

Suitbuilder Design Document

Date: 2026-01-30 Status: In Progress Reference: magsuitalgo.md (detailed MagSuitBuilder algorithm analysis)

---

Section 1: Problem Statement & Goals

What is Suitbuilder?

Suitbuilder helps players find the best equipment combination from their inventory across multiple "mule" characters. In Asheron's Call, players have many characters storing thousands of armor pieces, jewelry, and accessories. Finding the optimal combination manually is impractical.

Why is this hard?

The naive approach would check every possible combination: if you have 50 items per slot across 17 equipment slots, that's 50^17 combinations - more than atoms in the universe. MagSuitBuilder solved this with smart algorithms, and we're replicating that approach.

Main Goal - Priority Order

Given user constraints, find equipment combinations that:

1. Complete armor set bonuses (5 pieces primary set + 4 pieces secondary set) - HIGHEST PRIORITY
2. Cover all required spells/cantrips without duplicates
3. Maximize armor protection - LOWEST PRIORITY (tiebreaker)

Why we're doing this

The original MagSuitBuilder is a Windows desktop app. We want this functionality in our web-based Dereth Tracker so players can search their inventories from any browser.

---

Section 2: Algorithm Overview

The Bucket Approach

Instead of checking all item combinations, we organize items into "buckets" by equipment slot (Head, Chest, Hands, etc.). Then we search through buckets one at a time using recursion with backtracking.

How it works

1. Create buckets - One bucket per equipment slot (11 armor slots + jewelry slots)
2. Sort buckets - Process smallest buckets first (fewer branches to explore)
3. Recursive search - Try each item in bucket 1, then recurse to bucket 2, etc.
4. Backtrack - When a branch fails constraints, undo and try next item
5. Skip allowed - Can skip a slot entirely (incomplete suit better than constraint violation)

Why this is fast

• Bucket with 20 items × bucket with 15 items × bucket with 10 items = 3,000 combinations
• vs. checking every item against every other item = millions of combinations

Two-Phase Search (from MagSuitBuilder)

1. Phase 1 - ArmorSearcher: Find optimal armor combinations (enforces set constraints)
2. Phase 2 - AccessorySearcher: Add jewelry to complete spell coverage

Key Data Structures

• Spell Bitmap: 32-bit integer where each bit = one spell. Overlap detection is instant via bitwise OR
• Coverage Mask: Tracks which body areas are covered to prevent conflicts
• Set Counter: Tracks pieces per armor set (max 5 primary, 4 secondary)

---

Section 3: Current Implementation State

What's Working

• Spell Bitmap System - Correctly implements O(1) spell overlap detection
• Armor Set Constraints - 5+4 logic matches MagSuitBuilder exactly
• Coverage Mask - Body area tracking with reduction logic for multi-slot items
• API Endpoints - /search, /characters, /sets all functional
• Streaming Results - SSE (Server-Sent Events) for real-time feedback
• Frontend - suitbuilder.html and suitbuilder.js exist and connect to API

What's Broken

• Incomplete Bucket Creation - Only creates 2 buckets (Chest + Head) instead of 11+ slots
• Search Exits Early - Returns first result instead of completing full search
• No Item Sorting - Items processed in database order, not optimal order (best items first)
• Goes in Circles - Previous development sessions made inconsistent changes

What's Missing

• AccessorySearcher Phase - Jewelry optimization not implemented
• Item Pre-Filtering - No "surpassing logic" to remove inferior items before search
• Progressive Result Tracking - Should track top-N suits per piece count
• Proper Scoring - Needs to score by: set completion > spell coverage > armor level

Code Structure

• suitbuilder.py: 1,847 lines
• Main solver class (ConstraintSatisfactionSolver): ~1,130 lines

---

Section 4: Implementation Plan

Approach: Fix incrementally, verify after each step.

Each task is small, self-contained, and testable. Complete one fully before starting the next.

---

Task 1: Audit & Document Current Search Flow

Goal: Understand exactly what the current code does before changing it

Steps:

• Trace through ConstraintSatisfactionSolver.search() and document the flow
• Identify where buckets are created (find the 2-bucket limitation)
• Identify where search exits early
• Write findings as comments or separate doc

Verify: Can explain the current flow without looking at code

---

Task 2: Fix Bucket Creation

Goal: Create buckets for all 11 armor/clothing slots

Steps:

• Find bucket creation code
• Add missing slots: Head, Chest, Abdomen, Upper Arms, Lower Arms, Hands, Upper Legs, Lower Legs, Feet, plus clothing slots
• Ensure items are placed in correct buckets based on EquipMask

Verify: Log bucket counts - should see items distributed across 11+ buckets, not just 2

---

Task 3: Fix Search Completion

Goal: Search processes ALL buckets before returning results

Steps:

• Find early exit condition
• Remove or fix it so recursion continues through all buckets
• Ensure backtracking works correctly

Verify: Search logs show "processing bucket 1... bucket 2... bucket 11..." not stopping at 2

---

Task 4: Add Item Sorting

Goal: Process best items first for better pruning

Steps:

• Sort armor items by: set membership → armor level (descending)
• Sort within each bucket before search begins

Verify: Log first 5 items per bucket - should be highest armor level items

---

Task 5: Implement Proper Scoring

Goal: Score suits by correct priority order

Steps:

• Score = (set_completion × 10000) + (spell_coverage × 100) + armor_level
• Set completion = count of pieces matching primary/secondary sets
• Update CompletedSuit scoring logic

Verify: Given two suits, the one with better set completion always scores higher regardless of armor

---

Task 6: Add Item Pre-Filtering

Goal: Remove inferior items before search to reduce search space

Steps:

• Implement "surpassing logic": item A surpasses item B if A has same slot, same set, better stats, and equal/better spells
• Filter out surpassed items before bucketing

Verify: Log shows "Filtered X items down to Y items" with significant reduction

---

Task 7: Add AccessorySearcher Phase (Future)

Goal: After armor search, optimize jewelry slots

Scope: Separate task, do after Tasks 1-6 are solid

---

How to Use This Document

For Claude (AI assistant):

• Read this document at the start of each session
• Work on ONE task at a time
• Verify before moving to next task
• If confused, re-read the relevant section
• Do NOT make changes outside the current task scope

For the developer:

• Update "Status" at top when tasks complete
• Add notes under each task as we learn things
• Reference magsuitalgo.md for detailed algorithm explanations

---

Progress Tracking

Task	Status	Notes
Task 1: Audit Current Flow	Not Started
Task 2: Fix Bucket Creation	Not Started
Task 3: Fix Search Completion	Not Started
Task 4: Add Item Sorting	Not Started
Task 5: Implement Proper Scoring	Not Started
Task 6: Add Item Pre-Filtering	Not Started
Task 7: AccessorySearcher	Not Started	Future