first commit
This commit is contained in:
Beyhan Oğur
+352
@@ -0,0 +1,352 @@
|
||||
# Entity System Architecture
|
||||
|
||||
<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)
|
||||
- [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)
|
||||
</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)
|
||||
|
||||
## 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
|
||||
|
||||
```mermaid
|
||||
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](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)
|
||||
|
||||
## 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
|
||||
|
||||
```mermaid
|
||||
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**
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
## 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**
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
### 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**
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
### 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**
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
### 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**
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
### 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**
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [GumpCollection.cs](file://ClassicAssist.Shared/UO/Objects/GumpCollection.cs)
|
||||
|
||||
## 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
|
||||
|
||||
```mermaid
|
||||
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](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [GumpCollection.cs](file://ClassicAssist.Shared/UO/Objects/GumpCollection.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/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**
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user