ClassicAssist.Avalonia/.qoder/repowiki/en/content/API Reference/Data Models.md

# Data Models

<cite>
**Referenced Files in This Document**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
</cite>

## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)

## Introduction
This document describes the core data models used by ClassicAssist.Avalonia, focusing on game entities and configuration objects. It covers the Entity hierarchy (Entity base class, Mobile for living creatures, Item for game objects), scripting storage via MacroEntry, and key binding configuration via HotkeyEntry. For each model, we define fields, types, validation rules, serialization formats, relationships, lifecycle methods, access patterns, caching strategies, performance considerations, migration paths, version compatibility, and backup/restore procedures.

## Project Structure
The relevant data models are primarily located under:
- Game entities: ClassicAssist.Shared/UO/Objects
- Configuration and macros: ClassicAssist.Shared/Data/Macros and ClassicAssist.Shared/Data/Hotkeys
- Global options: ClassicAssist.Shared/Data

```mermaid
graph TB
subgraph "Game Objects"
E["Entity"]
M["Mobile"]
I["Item"]
PM["PlayerMobile"]
P["Property"]
end
subgraph "Configuration"
ME["MacroEntry"]
HE["HotkeyEntry"]
OPT["Options"]
AO["AssistantOptions"]
end
E --> M
E --> I
M --> PM
I --> P
OPT --> ME
OPT --> HE
```

[No sources needed since this diagram shows conceptual structure]

## Core Components
- Entity: Base type for all in-game objects with identity, location, and state.
- Mobile: Living entity extending Entity with movement, combat, and status attributes.
- Item: Inanimate object extending Entity with container semantics and properties.
- PlayerMobile: Specialized Mobile representing the local player.
- Property: Key-value pair attached to Items.
- MacroEntry: Script definition and metadata for macro execution.
- HotkeyEntry: Key binding configuration mapping keys to commands.
- Options and AssistantOptions: Application-level settings containers.

Key responsibilities:
- Identity and lifetime management for entities.
- Composition of properties for items.
- Storage and invocation of macro scripts.
- Binding hotkeys to commands.
- Centralized application configuration.

**Section sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

## Architecture Overview
The data model follows a clear inheritance hierarchy for game objects and a composition pattern for configuration and scripting. Entities form a tree-like world model where Items can contain other Items and hold Properties. Macros and hotkeys are persisted as part of application options.

```mermaid
classDiagram
class Entity {
+int Serial
+string Name
+int Hue
+int X
+int Y
+int Z
+int Map
+bool Visible
+bool Deleted
+void Update()
+void Dispose()
}
class Mobile {
+int Body
+int Stamina
+int Mana
+int Hits
+bool IsDead
+void MoveTo(x,y,z)
+void Attack(target)
}
class Item {
+int Amount
+int Layer
+Property[] Properties
+void AddProperty(key,value)
+void RemoveProperty(key)
}
class PlayerMobile {
+bool IsLocalPlayer
+void CastSpell(spellId)
}
class Property {
+string Key
+string Value
}
class MacroEntry {
+string Name
+string Category
+string Script
+bool Enabled
+void Execute()
}
class HotkeyEntry {
+string Command
+string Keys
+bool Enabled
+void Bind()
+void Unbind()
}
class Options {
+MacroEntry[] Macros
+HotkeyEntry[] Hotkeys
+void Save()
+void Load()
}
class AssistantOptions {
+string Language
+bool EnableDebug
+void Apply()
}
Entity <|-- Mobile
Entity <|-- Item
Mobile <|-- PlayerMobile
Item --> Property : "has many"
Options --> MacroEntry : "contains"
Options --> HotkeyEntry : "contains"
```

**Diagram sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

## Detailed Component Analysis

### Entity Hierarchy
- Entity
  - Purpose: Base representation of any in-world object.
  - Key fields: serial identifier, name, hue, coordinates (X, Y, Z), map, visibility flags, deletion state.
  - Lifecycle: creation upon packet processing, update on incoming updates, disposal when removed.
  - Methods: update hooks, disposal/cleanup.
- Mobile
  - Extends Entity; represents living creatures.
  - Additional fields: body type, stamina, mana, hits, death state.
  - Methods: movement, attack, status updates.
- Item
  - Extends Entity; represents inanimate objects.
  - Additional fields: amount, layer, collection of Property entries.
  - Methods: property management, container operations.
- PlayerMobile
  - Specialization of Mobile for the local player.
  - Additional behavior: spell casting, local-only flags.

Validation rules:
- Coordinates within valid ranges per map.
- Non-negative amounts for Items.
- Valid hues and body IDs.

Serialization format:
- Typically serialized via binary packets from the game client; persistence uses JSON/XML through Options.

Relationships:
- Items may contain other Items (container hierarchy).
- Items have zero or more Properties.

Lifecycle methods:
- OnCreate: initialize defaults.
- OnUpdate: apply incremental changes.
- OnRemove: cleanup resources and references.

Data access patterns:
- Use collections to query by serial, name, or filters.
- Cache frequently accessed entities to reduce lookup overhead.

Caching strategies:
- Maintain an in-memory index keyed by serial.
- Invalidate cache on removal or significant updates.

Performance considerations:
- Avoid deep traversals during hot loops; prefer indexed lookups.
- Batch updates to minimize UI refreshes.

Migration and compatibility:
- Introduce versioned schema for new fields; provide default values for older versions.
- Validate and normalize legacy data on load.

Backup/restore:
- Export entity snapshots for debugging; restore only in controlled environments.

**Section sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)

#### Class Diagram: Entity Hierarchy
```mermaid
classDiagram
class Entity
class Mobile
class Item
class PlayerMobile
class Property
Entity <|-- Mobile
Entity <|-- Item
Mobile <|-- PlayerMobile
Item --> Property
```

**Diagram sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)

### Property Model
- Purpose: Attach arbitrary key-value metadata to Items.
- Fields: key (string), value (string).
- Validation: unique keys per Item; non-empty key.
- Serialization: embedded in Item’s serialized form.
- Access patterns: dictionary-style lookup by key; iterate for bulk operations.

**Section sources**
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)

### MacroEntry
- Purpose: Store macro script definitions and metadata.
- Fields: name, category, script content, enabled flag.
- Validation: non-empty name; script syntax checked at runtime.
- Serialization: stored within Options as a list of MacroEntry.
- Execution: invoked via MacroManager; supports parameters and command context.

Access patterns:
- List-based enumeration for UI.
- Filter by category or enabled state.

Caching:
- Pre-parse and cache compiled representations if applicable.

Performance:
- Avoid heavy parsing on every execution; cache parsed forms.

Migration:
- Version macro schemas; provide converters for old formats.

Backup/restore:
- Include macros in profile exports; validate on import.

**Section sources**
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)

### HotkeyEntry
- Purpose: Define key bindings to commands.
- Fields: command string, key combination, enabled flag.
- Validation: valid key combination; command exists in registry.
- Serialization: stored within Options as a list of HotkeyEntry.
- Lifecycle: bind/unbind on enable/disable; persist changes.

Access patterns:
- Lookup by command or key combination.
- Iterate to render UI and manage active bindings.

Caching:
- Maintain a map from key combinations to entries for fast dispatch.

Performance:
- Minimize reflection during hot path; resolve commands once.

Migration:
- Normalize legacy key formats; deprecate obsolete commands gracefully.

Backup/restore:
- Export/import hotkeys alongside profiles; warn on conflicts.

**Section sources**
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)

### Options and AssistantOptions
- Options
  - Holds global lists of MacroEntry and HotkeyEntry.
  - Provides Save/Load for persistence.
- AssistantOptions
  - Holds user preferences such as language and debug toggles.
  - Applies settings at runtime.

Validation:
- Ensure required sections exist; coerce missing fields to defaults.

Serialization:
- JSON or XML depending on platform; consistent across profiles.

Migration:
- Schema versioning with upgraders; backward-compatible reads.

Backup/restore:
- Profile export includes Options and AssistantOptions; integrity checks on import.

**Section sources**
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

## Dependency Analysis
- Entity depends on minimal primitives; Mobile and Item extend it.
- Item composes Property instances.
- Options aggregates MacroEntry and HotkeyEntry.
- AssistantOptions is independent but consumed by Options.

```mermaid
graph LR
Entity --> Mobile
Entity --> Item
Mobile --> PlayerMobile
Item --> Property
Options --> MacroEntry
Options --> HotkeyEntry
Options --> AssistantOptions
```

**Diagram sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

**Section sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

## Performance Considerations
- Prefer indexed lookups over linear scans for large entity sets.
- Batch UI updates to avoid excessive redraws.
- Cache parsed macro scripts and resolved hotkey commands.
- Avoid deep recursion when traversing item containers; use iterative approaches.
- Use lightweight DTOs for serialization to reduce allocations.

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- Missing fields after upgrade: ensure default values are applied during load.
- Invalid key combinations: validate and prompt user to rebind.
- Macro execution errors: check script syntax and available commands.
- Entity not found: verify serial validity and presence in current map.

Operational checks:
- Validate Options schema before applying.
- Log warnings for deprecated features.
- Provide rollback on failed imports.

**Section sources**
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)

## Conclusion
The data models in ClassicAssist.Avalonia are organized around a clean Entity hierarchy for game objects and robust configuration structures for macros and hotkeys. By following the recommended access patterns, caching strategies, and migration practices, developers can maintain high performance and reliable upgrades while ensuring user data portability and safety.

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

## Appendices

### Field Definitions Summary
- Entity: identity, appearance, position, visibility, lifecycle flags.
- Mobile: creature stats and combat-related fields.
- Item: quantity, layer, and associated properties.
- Property: key-value metadata.
- MacroEntry: script metadata and content.
- HotkeyEntry: command and key binding.
- Options: aggregated configuration lists.
- AssistantOptions: user preferences.

**Section sources**
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)

### Data Flow Example: Hotkey Dispatch
```mermaid
sequenceDiagram
participant User as "User"
participant OS as "OS Input"
participant HK as "HotkeyEntry"
participant Cmd as "Command Registry"
participant Exec as "Executor"
User->>OS : Press key combination
OS-->>HK : Key event
HK->>Cmd : Resolve command by name
Cmd-->>HK : Command handler
HK->>Exec : Invoke handler with context
Exec-->>User : Action performed
```

**Diagram sources**
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)

### Data Flow Example: Macro Execution
```mermaid
sequenceDiagram
participant UI as "UI"
participant ME as "MacroEntry"
participant MM as "MacroManager"
participant VM as "VM Context"
UI->>ME : Select macro
UI->>MM : Execute(ME)
MM->>ME : Prepare script
MM->>VM : Build execution context
MM-->>UI : Result/status
```

**Diagram sources**
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)