Beyhan Oğur
13 KiB
13 KiB
Entity System Architecture
**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) - [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs) - [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs) - [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs) - [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs) - [GumpCollection.cs](file://ClassicAssist.Shared/UO/Objects/GumpCollection.cs) - [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs) - [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document explains the ClassicAssist.Avalonia entity system architecture with a focus on:
- The Entity base class hierarchy and shared properties/methods/events
- Mobile implementation for player characters, NPCs, creatures, and movement systems
- Item object model including inventory items, equipment slots, container hierarchies, and property systems
- Gump rendering system for interactive UI elements and dialog boxes
- Entity collection management, filtering, sorting, and performance optimization strategies
- Entity lifecycle events, state synchronization between client and server, and memory management considerations
The goal is to make the system understandable for both new contributors and experienced developers while providing actionable guidance for extension and maintenance.
Project Structure
The entity system lives primarily under ClassicAssist.Shared/UO/Objects and related subfolders. Key areas include:
- Core entities: Entity, Mobile, PlayerMobile, Item
- Collections: EntityCollection, MobileCollection, ItemCollection, GumpCollection
- UI layer: Gumps and associated collections
- Properties: Property model used by Items and other objects
graph TB
subgraph "UO Objects"
E["Entity"]
M["Mobile"]
PM["PlayerMobile"]
I["Item"]
P["Property"]
EC["EntityCollection"]
MC["MobileCollection"]
IC["ItemCollection"]
GC["GumpCollection"]
end
subgraph "Gumps"
G["Gump"]
GP["GumpPage"]
GE["GumpElement"]
end
E --> M
M --> PM
E --> I
I --> P
EC --> E
MC --> M
IC --> I
GC --> G
G --> GP
GP --> GE
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
Core Components
- Entity base class provides common identity, location, visibility, and lifecycle hooks used across all game objects.
- Mobile extends Entity to represent living beings (players, NPCs, creatures) with movement, targeting, and combat-related behavior.
- Item extends Entity to represent world and inventory objects, containers, equipment, and dynamic properties.
- Gump represents interactive UI windows and pages, with elements that respond to user input.
- Collections manage sets of entities with efficient lookup, filtering, and iteration.
Key responsibilities:
- Identity and lifetime management
- Spatial coordinates and map context
- Event-driven updates and notifications
- Network synchronization points
- UI integration via gumps and bindings
Section sources
- Entity.cs
- Mobile.cs
- Item.cs
- Gump.cs
- EntityCollection.cs
- ItemCollection.cs
- MobileCollection.cs
- GumpCollection.cs
- Property.cs
- PlayerMobile.cs
Architecture Overview
The entity system follows a layered design:
- Base layer: Entity defines universal attributes and behaviors
- Specialized layers: Mobile and Item inherit from Entity and add domain-specific features
- UI layer: Gumps provide interactive overlays and dialogs
- Collection layer: Typed collections optimize storage, lookup, and queries
classDiagram
class Entity {
+Id
+Map
+X
+Y
+Z
+Visible
+OnCreated()
+OnUpdated()
+OnRemoved()
}
class Mobile {
+Hue
+Body
+Name
+Direction
+Speed
+Target
+MoveTo(target)
+UpdateMovement()
}
class PlayerMobile {
+Skills
+Stats
+Equipment
+Inventory
}
class Item {
+Serial
+Layer
+Stackable
+Properties
+Container
+Use()
+Inspect()
}
class Gump {
+PageCount
+Show()
+Hide()
+HandleClick(button)
}
class GumpPage
class GumpElement
class Property
Entity <|-- Mobile
Mobile <|-- PlayerMobile
Entity <|-- Item
Item --> Property : "has many"
Gump --> GumpPage : "contains"
GumpPage --> GumpElement : "contains"
Diagram sources
Detailed Component Analysis
Entity Base Class Hierarchy
Common responsibilities:
- Unique identification and association with maps and locations
- Visibility flags and update cycles
- Lifecycle hooks for creation, updates, and removal
- Event emission for subscribers (e.g., position changes, visibility toggles)
Shared properties typically include:
- Identifier fields for network and local tracking
- Map and coordinate fields for spatial queries
- Flags for visibility and active state
- Timestamps or versioning for synchronization
Event patterns:
- OnCreated/OnUpdated/OnRemoved for lifecycle
- PropertyChanged-style notifications for key attributes
- Custom events for movement, targeting, and interaction
Optimization notes:
- Avoid heavy work in event handlers; prefer batching where possible
- Use weak references for listeners to prevent leaks
- Coalesce frequent updates (e.g., position deltas) before notifying
Section sources
Mobile Implementation
Mobile models living entities such as players, NPCs, and creatures. It adds:
- Appearance: hue, body type, name
- Movement: direction, speed, pathfinding integration
- Targeting: current target, auto-target logic
- Combat state: aggression flags, status effects (via properties)
Movement system:
- Requests movement through packet-based commands
- Interpolates or applies server-authoritative positions
- Integrates with pathfinding to avoid obstacles
- Handles mount states and special movement modes
Lifecycle and sync:
- Incoming packets update mobile state
- Outgoing requests initiate actions (move, attack, use skill)
- Local prediction may be used for responsiveness, reconciled with server state
Section sources
Item Object Model
Item represents physical and virtual objects:
- World items and inventory items
- Containers and nested hierarchies
- Equipment slots and layer associations
- Dynamic properties and custom data
Key concepts:
- Serial and parent/container relationships define ownership
- Layer indicates equipment slot when equipped
- Stackable flag supports quantity semantics
- Property list enables rich metadata and UI binding
Container hierarchies:
- Parent-child relationships form trees
- Updates propagate content changes efficiently
- Bulk operations minimize packet overhead
Property systems:
- Standard properties (name, description, stats)
- Custom properties for modding and automation
- Batched property queries reduce network traffic
Section sources
Gump Rendering System
Gumps provide interactive UI overlays:
- Pages and elements compose complex interfaces
- Click and input handling routes to application logic
- Show/hide lifecycle integrates with window managers
Rendering and interaction:
- Elements are laid out per page
- Events bubble up to gump handlers
- Binding to entity/item properties drives dynamic UI
Best practices:
- Keep gumps lightweight; offload heavy tasks to background threads
- Reuse gump instances where possible
- Debounce rapid user interactions
Section sources
Entity Collection Management
Collections provide optimized storage and querying:
- EntityCollection manages generic entities
- MobileCollection and ItemCollection specialize for typed access
- GumpCollection manages UI overlays
Features:
- Fast lookup by ID or serial
- Filtering by criteria (type, map, range, tags)
- Sorting by attributes (distance, name, timestamp)
- Efficient iteration for rendering and updates
Performance strategies:
- Indexes for frequently queried fields
- Lazy evaluation for filters and sorts
- Batching updates to reduce churn
- Memory pooling for transient query results
Section sources
Dependency Analysis
High-level dependencies:
- Mobile and Item depend on Entity for core functionality
- PlayerMobile specializes Mobile for player-specific data
- Item uses Property for metadata and dynamic values
- Gumps interact with Entities and Items via bindings and commands
- Collections depend on their respective entity types for indexing and queries
graph LR
Entity --> Mobile
Mobile --> PlayerMobile
Entity --> Item
Item --> Property
EntityCollection --> Entity
MobileCollection --> Mobile
ItemCollection --> Item
GumpCollection --> Gump
Gump --> Entity
Gump --> Item
Diagram sources
- Entity.cs
- Mobile.cs
- PlayerMobile.cs
- Item.cs
- Property.cs
- EntityCollection.cs
- MobileCollection.cs
- ItemCollection.cs
- GumpCollection.cs
- Gump.cs
Performance Considerations
- Update batching: Group multiple entity updates into fewer notifications to reduce UI churn.
- Spatial queries: Use distance checks and bounding regions to limit expensive calculations.
- Property caching: Cache computed or remote property values with invalidation on change.
- Collection indexes: Maintain secondary indexes for hot paths (e.g., nearest neighbor).
- Event coalescing: Merge rapid successive events (position, visibility) before dispatch.
- Memory management: Clear references in removal hooks; avoid retaining large temporary structures.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Stale entity state: Ensure incoming packet handlers reconcile local predictions with authoritative server updates.
- Missing properties: Verify batched property queries complete and cache invalidation occurs on updates.
- UI lag: Offload heavy computations from UI thread; debounce user inputs; reuse gump instances.
- Memory growth: Check for lingering event subscriptions; ensure removal hooks release resources.
- Container inconsistencies: Validate parent-child relationships after bulk updates; rebuild indices if necessary.
Section sources
Conclusion
The ClassicAssist.Avalonia entity system centers around a clean base Entity class extended by Mobile and Item, with robust collections and a flexible gump UI layer. By leveraging event-driven updates, efficient collections, and careful memory management, the system scales to handle thousands of entities and responsive UIs. Following the patterns outlined here will help maintain performance and correctness as the system evolves.