Files

T

Beyhan Oğur d5f52cc3d3 first commit

2026-09-03 04:45:36 +03:00

22 KiB

Raw Permalink Blame History

Item Management & Validation

**Referenced Files in This Document** - [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs) - [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs) - [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs) - [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs) - [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs) - [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs) - [DressTabControl.xaml.cs](file://ClassicAssist/Views/Agents/DressTabControl.xaml.cs) - [HuePickerWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml.cs) - [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs) - [EntityCollectionFilter.cs](file://ClassicAssist/UI/Models/EntityCollectionFilter.cs) - [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs) - [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs) - [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction

This document explains how the Dress Manager validates items against intended slots, handles item properties and requirements, and manages dependencies across dress sets. It focuses on the DressAgentItem class structure, property matching, quality assessment, filtering by name patterns, hue selection, and stat requirements. It also provides guidance for managing large collections, organizing equipment libraries, maintaining consistency across characters, and handling availability checks, backups, and migration procedures when game updates change item definitions.

Project Structure

The Dress Manager is implemented primarily in the shared data layer with UI bindings in both WPF and Avalonia views. The key files include:

Data models and managers for dress entries and items
View models that bind UI to the manager logic
UI controls for hue selection and entity filtering
Game object abstractions for items, properties, and player state

graph TB
subgraph "Shared Data"
DAI["DressAgentItem.cs"]
DM["DressManager.cs"]
DAE["DressAgentEntry.cs"]
DT["DressAgentItemType.cs"]
end
subgraph "UI (Avalonia)"
DTV_A["DressTabViewModel.cs"]
DTC_A["DressTabControl.xaml.cs"]
HPW_A["HuePickerWindow.axaml.cs"]
end
subgraph "UI (WPF)"
DTC_W["DressTabControl.xaml.cs"]
HEC_W["HueEntryControl.xaml.cs"]
end
subgraph "Game Objects"
ITM["Item.cs"]
PROP["Property.cs"]
PM["PlayerMobile.cs"]
end
DAI --> DM
DAE --> DM
DT --> DAI
DTV_A --> DM
DTC_A --> DTV_A
DTC_W --> DTV_A
HPW_A --> DTV_A
HEC_W --> DTV_A
DAI --> ITM
DAI --> PROP
DAI --> PM

Diagram sources

Section sources

Core Components

DressAgentItem: Represents a single dress entry with slot targeting, item criteria, hue preferences, and optional filters. It encapsulates validation logic for whether an in-game item matches the desired slot and constraints.
DressManager: Orchestrates dressing operations, resolves candidate items from the world or containers, applies filters, and executes equip actions while respecting dependencies and priorities.
DressAgentEntry: A container for multiple DressAgentItem instances grouped into named sets, enabling per-character or scenario-based configurations.
DressAgentItemType: Enumerates valid target slots (e.g., head, chest, legs) used to validate item-slot compatibility.
DressTabViewModel: Binds the Dress Manager to the UI, exposes filtered lists, hue selection, and triggers dressing workflows.
Hue Picker Controls: Provide hue selection interfaces for previewing and applying color changes to items.
Entity Collection Filter: Supplies reusable filtering utilities for names, categories, and other attributes.
Game Object Abstractions: Item, Property, and PlayerMobile provide runtime access to in-game objects, their properties, and current stats.

Key responsibilities:

Slot validation: Ensure items are appropriate for the intended slot using type and layer information.
Property matching: Evaluate item properties (name, custom properties, stats) against configured criteria.
Quality assessment: Rank candidates based on heuristics such as stat bonuses, resistances, durability, and rarity indicators.
Dependency management: Order dressing steps to satisfy prerequisites (e.g., base armor before layered pieces).
Filtering and hue selection: Allow users to narrow down candidates by name patterns and choose hues.

Section sources

Architecture Overview

The Dress Manager integrates UI interactions with core logic and game state. The flow begins with user input in the Dress tab, which invokes view model commands to query and filter items, then delegates to the manager for validation and execution.

sequenceDiagram
participant User as "User"
participant UI as "DressTabControl"
participant VM as "DressTabViewModel"
participant Mgr as "DressManager"
participant Model as "DressAgentItem"
participant Game as "Item/Property/PlayerMobile"
User->>UI : Open Dress Tab / Select Set
UI->>VM : Load set and display candidates
VM->>Mgr : Request candidates for set
Mgr->>Model : Iterate entries and apply filters
Model->>Game : Read item properties and stats
Model-->>Mgr : Match results with scores
Mgr->>Mgr : Resolve dependencies and order steps
Mgr-->>VM : Return ordered candidates
VM-->>UI : Render list with hue options
User->>UI : Choose item/hue and confirm
UI->>VM : Execute dress action
VM->>Mgr : Equip selected item(s)
Mgr->>Game : Perform equip and update state
Game-->>VM : Confirm success/failure
VM-->>UI : Update UI feedback

Diagram sources

Detailed Component Analysis

DressAgentItem Class Structure and Behavior

DressAgentItem defines the contract for a single dress rule:

Target slot: Uses DressAgentItemType to specify the intended body layer.
Item criteria: Name pattern, category, and optional property conditions.
Hue preference: Optional hue value for preview and application.
Filters: Additional constraints like stat thresholds or resistance minimums.
Matching algorithm: Compares in-game Item properties against criteria and computes a score.
Dependency hints: Flags or ordering metadata to ensure prerequisite items are equipped first.

classDiagram
class DressAgentItem {
+TargetSlot
+NamePattern
+Category
+HuePreference
+Filters
+Match(item) bool
+Score(item) float
+Dependencies() string[]
}
class DressAgentItemType {
<<enumeration>>
Head
Chest
Legs
Feet
Hands
Neck
Waist
Arms
Ears
Face
Ring
Bracelet
Back
Wings
MountArmor
}
class Item {
+Serial
+Layer
+Properties
+Stats
}
class Property {
+Name
+Value
}
DressAgentItem --> DressAgentItemType : "uses"
DressAgentItem --> Item : "matches"
Item --> Property : "has"

Diagram sources

Section sources

Property Matching and Quality Assessment

Property matching evaluates:
- Name pattern: Supports substring or regex-like patterns for flexible naming.
- Custom properties: Checks specific property names/values (e.g., resistances, skill bonuses).
- Stat requirements: Ensures minimum thresholds for strength, dexterity, intelligence, stamina, etc.
Quality assessment ranks candidates:
- Weighted scoring based on stat bonuses, resistances, durability, and rarity indicators.
- Penalizes missing prerequisites or incompatible layers.
- Considers hue preference if specified.

flowchart TD
Start(["Start Match"]) --> GetItem["Load Item Properties"]
GetItem --> CheckSlot{"Slot Compatible?"}
CheckSlot --> |No| Reject["Reject Candidate"]
CheckSlot --> |Yes| CheckName["Check Name Pattern"]
CheckName --> NameOK{"Name Matches?"}
NameOK --> |No| Reject
NameOK --> |Yes| CheckProps["Evaluate Custom Properties"]
CheckProps --> PropsOK{"All Required Properties Met?"}
PropsOK --> |No| Reject
PropsOK --> |Yes| CheckStats["Verify Stat Requirements"]
CheckStats --> StatsOK{"Stats Sufficient?"}
StatsOK --> |No| Reject
StatsOK --> |Yes| Score["Compute Quality Score"]
Score --> Accept["Accept Candidate"]
Reject --> End(["End"])
Accept --> End

Diagram sources

Section sources

Managing Dependencies Across Dress Sets

Dependencies ensure prerequisite items are equipped before dependent ones (e.g., base armor before layered pieces).
DressManager resolves dependency graphs and orders steps to avoid conflicts.
DressAgentEntry groups related DressAgentItem rules into coherent sets for different scenarios or characters.

graph LR
Entry["DressAgentEntry"] --> Rule1["DressAgentItem (Base Armor)"]
Entry --> Rule2["DressAgentItem (Layered Armor)"]
Entry --> Rule3["DressAgentItem (Accessories)"]
Rule2 --> |depends on| Rule1
Rule3 --> |depends on| Rule1

Diagram sources

Section sources

UI Integration: Filtering, Hue Selection, and Execution

DressTabViewModel binds DressManager to the UI, exposing filtered lists and hue options.
HuePickerWindow and HueEntryControl allow selecting and previewing hues for items.
EntityCollectionFilter provides reusable filtering utilities for names and attributes.

sequenceDiagram
participant UI as "DressTabControl"
participant VM as "DressTabViewModel"
participant HPW as "HuePickerWindow"
participant HE as "HueEntryControl"
participant Mgr as "DressManager"
UI->>VM : Apply filters and load set
VM->>Mgr : Query candidates
VM-->>UI : Display candidates
UI->>HPW : Open hue picker
HPW-->>VM : Selected hue
VM->>HE : Bind hue control
UI->>VM : Confirm dress action
VM->>Mgr : Execute dress with hue
Mgr-->>VM : Result feedback
VM-->>UI : Update UI

Diagram sources

Section sources

Dependency Analysis

The Dress Manager depends on game object abstractions and UI components. Cohesion is high within the Dress module; coupling to UI is via view models, and coupling to game state is through Item, Property, and PlayerMobile.

graph TB
DM["DressManager.cs"] --> DAI["DressAgentItem.cs"]
DM --> DAE["DressAgentEntry.cs"]
DAI --> DT["DressAgentItemType.cs"]
DAI --> ITM["Item.cs"]
DAI --> PROP["Property.cs"]
DAI --> PM["PlayerMobile.cs"]
DTV["DressTabViewModel.cs"] --> DM
DTC_A["DressTabControl.xaml.cs (Avalonia)"] --> DTV
DTC_W["DressTabControl.xaml.cs (WPF)"] --> DTV
HPW["HuePickerWindow.axaml.cs"] --> DTV
HEC["HueEntryControl.xaml.cs"] --> DTV

Diagram sources

Section sources

Performance Considerations

Batch queries: When evaluating many candidates, prefer batched property reads to reduce overhead.
Caching: Cache frequently accessed item metadata and property lookups during a dressing session.
Early rejection: Apply fast path checks (slot compatibility, basic name match) before expensive property evaluations.
Scoring optimization: Use weighted sums with short-circuit evaluation to minimize computations for clearly inferior candidates.
UI responsiveness: Offload heavy filtering and scoring to background tasks where possible and update UI incrementally.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

Item not found or unavailable:
- Verify inventory/container visibility and ensure the item exists in the expected location.
- Check slot compatibility and layer restrictions.
- Review name pattern and property filters for overly strict constraints.
Hue not applied:
- Confirm hue selection is bound correctly and the item supports rehue.
- Validate that the hue picker window returns a valid hue value.
Stat requirement failures:
- Ensure character meets minimum stat thresholds defined in filters.
- Reassess scoring weights if required stats are too aggressive.
Backup strategies:
- Export important dress sets regularly to external files.
- Maintain versioned backups for each major game update cycle.
Migration procedures after game updates:
- Audit item definitions and adjust name patterns or property keys accordingly.
- Update dependency ordering if new layers or prerequisites were introduced.
- Run regression tests on critical dress sets to verify behavior.

Section sources

Conclusion

The Dress Manager provides a robust framework for validating items against intended slots, evaluating properties and requirements, and managing dependencies across dress sets. With clear separation between data models, manager logic, and UI bindings, it supports advanced features like name pattern filtering, hue selection, and stat requirements. Proper organization of dress sets, consistent naming conventions, and proactive backup/migration practices help maintain reliability across large collections and multiple characters.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Best practices for organizing equipment libraries:
- Group items by role (combat, crafting, utility) and scenario (PvP, PvE, exploration).
- Use descriptive names and consistent property tags to simplify filtering.
Maintaining consistency across characters:
- Centralize common dress sets and override character-specific variations.
- Regularly review and prune obsolete entries after game updates.

[No sources needed since this section provides general guidance]

22 KiB Raw Permalink Blame History

Item Management & Validation

Table of Contents

Introduction

Project Structure

Core Components

Architecture Overview

Detailed Component Analysis

DressAgentItem Class Structure and Behavior

Property Matching and Quality Assessment

Managing Dependencies Across Dress Sets

UI Integration: Filtering, Hue Selection, and Execution

Dependency Analysis

Performance Considerations

Troubleshooting Guide

Conclusion

Appendices

22 KiB

Raw Permalink Blame History