Game Frame X Entity Component

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams

Documentation · Quick Start · QQ Group: 467608841 / 233840761

English | 简体中文 | 繁體中文 | 日本語 | 한국어

Table of Contents

• Project Overview
• Key Features
• Quick Start
  • Installation
• Usage Examples
  • 1. Define EntityLogic
  • 2. Show Entity
  • 3. Hide Entity
  • 4. Parent-Child Hierarchy
  • 5. Subscribe to Events
• Entity Lifecycle
• Architecture
• Documentation & Resources
• Community & Support
• Changelog
• License

Project Overview

The Entity Component provides a complete entity management system for Unity games. It handles entity lifecycle (show, hide, recycle), grouping, parent-child hierarchy, and integrates with the asset system for async resource loading and object pools for instance reuse.

Built on top of the GameFrameX framework, it uses UniTask for async operations and provides a Manager-Component-Helper layered architecture.

Key Features

• Async Entity Spawning — Load and instantiate entities asynchronously via UniTask, with progress and dependency callbacks
• Entity Grouping — Organize entities into groups with individual object pool settings (capacity, expire time, auto-release interval)
• Parent-Child Hierarchy — Attach/detach child entities with automatic Transform parenting
• Object Pool Integration — Reuse entity instances through object pools for memory efficiency
• Event-Driven Lifecycle — Subscribe to Show/Hide/Update/DependencyAsset events for reactive workflows
• EntityLogic Pattern — Implement business logic by subclassing EntityLogic with OnInit/OnShow/OnHide/OnUpdate lifecycle methods
• Instance Management — Lock entity instances or adjust priority for pool eviction control

Quick Start

Installation

Choose one of the following methods:

1. Edit your Unity project's Packages/manifest.json and add the scopedRegistries section:

   {
     "scopedRegistries": [
       {
         "name": "GameFrameX",
         "url": "https://gameframex.upm.alianblank.uk",
         "scopes": [
           "com.gameframex"
         ]
       }
     ],
     "dependencies": {
       "com.gameframex.unity.entity": "2.4.3"
     }
   }

   scopes controls which packages are resolved through this registry. Only packages whose names start with com.gameframex will be fetched from it.

2. Add to manifest.json dependencies:

   {
      "com.gameframex.unity.entity": "https://github.com/gameframex/com.gameframex.unity.entity.git"
   }

3. Use Package Manager in Unity with Git URL: https://github.com/gameframex/com.gameframex.unity.entity.git

4. Clone the repository into your Unity project's Packages directory. It will be loaded automatically.

Usage Examples

1. Define EntityLogic

Create a subclass of EntityLogic to implement your entity's behavior:

using GameFrameX.Entity.Runtime;
using UnityEngine;

public class PlayerEntity : EntityLogic
{
    protected internal override void OnInit(object userData)
    {
        base.OnInit(userData);
        // Initialize component references, etc.
    }

    protected internal override void OnShow(object userData)
    {
        base.OnShow(userData);
        // Called when the entity is shown
    }

    protected internal override void OnHide(bool isShutdown, object userData)
    {
        base.OnHide(isShutdown, userData);
        // Called when the entity is hidden
    }

    protected internal override void OnUpdate(float elapseSeconds, float realElapseSeconds)
    {
        base.OnUpdate(elapseSeconds, realElapseSeconds);
        // Per-frame update logic
    }
}

2. Show Entity

Use EntityComponent to asynchronously spawn an entity:

// Get the EntityComponent
var entityComponent = GameEntry.GetComponent<EntityComponent>();

// Show entity asynchronously
IEntity entity = await entityComponent.ShowEntityAsync<PlayerEntity>(
    entityId: 1,
    entityAssetName: "Assets/Prefabs/Player.prefab",
    entityGroupName: "PlayerGroup"
);

3. Hide Entity

// Hide by entity ID
entityComponent.HideEntity(1);

// Hide by entity reference
entityComponent.HideEntity(entity);

// Hide all loaded entities
entityComponent.HideAllLoadedEntities();

4. Parent-Child Hierarchy

Attach child entities to form parent-child relationships:

// Attach child to parent
entityComponent.AttachEntity(childEntity, parentEntity);

// Attach with a specific Transform path
entityComponent.AttachEntity(childEntity, parentEntity, "Weapon/RightHand");

// Detach child
entityComponent.DetachEntity(childEntity);

// Detach all children of a parent
entityComponent.DetachChildEntities(parentEntity);

5. Subscribe to Events

entityComponent.ShowEntitySuccess += (sender, e) =>
{
    Debug.Log($"Entity shown: {e.Entity.Id}");
};

entityComponent.ShowEntityFailure += (sender, e) =>
{
    Debug.LogError($"Entity failed: {e.ErrorMessage}");
};

entityComponent.HideEntityComplete += (sender, e) =>
{
    Debug.Log($"Entity hidden: {e.EntityId}");
};

Entity Lifecycle

Stage	Method	Description
Init	OnInit(object userData)	First-time initialization, cache references
Show	OnShow(object userData)	Entity becomes visible and active
Update	OnUpdate(float, float)	Per-frame update when entity is shown
Hide	OnHide(bool isShutdown, object userData)	Entity is hidden
Recycle	OnRecycle()	Entity returned to object pool

Parent-child events:

Event	Parent	Child
Attach	OnAttached(childEntity, parentTransform, userData)	OnAttachTo(parentEntity, parentTransform, userData)
Detach	OnDetached(childEntity, userData)	OnDetachFrom(parentEntity, userData)

Architecture

Runtime/
├── Entity/
│   ├── EntityComponent.cs       # Unity MonoBehaviour bridge
│   ├── EntityLogic.cs           # Base class for entity behavior
│   ├── EntityHelperBase.cs      # Abstract helper for instantiation/release
│   ├── EntityGroupHelperBase.cs # Abstract helper for entity groups
│   ├── Entity/
│   │   ├── IEntityManager.cs    # Core manager interface
│   │   ├── EntityManager.cs     # Manager implementation (partial class)
│   │   ├── IEntity.cs           # Entity interface
│   │   ├── IEntityGroup.cs      # Entity group interface
│   │   └── ...
│   ├── ShowEntityInfo.cs        # Show entity parameters
│   └── AttachEntityInfo.cs      # Attach entity parameters
├── EventArgs/                   # Lifecycle event args
│   ├── ShowEntitySuccessEventArgs.cs
│   ├── ShowEntityFailureEventArgs.cs
│   ├── ShowEntityUpdateEventArgs.cs
│   ├── ShowEntityDependencyAssetEventArgs.cs
│   └── HideEntityCompleteEventArgs.cs
└── Editor/Inspector/            # Custom Inspector

Documentation & Resources

• Documentation

Community & Support

• QQ Group: 467608841 / 233840761

Changelog

See Releases for changelog.

Dependencies

Package	Description
com.gameframex.unity.asset	2.5.0
com.gameframex.unity.event	1.1.0

Documentation & Resources

• Documentation

Community & Support

• QQ Group: 467608841 / 233840761

Changelog

See Releases for changelog.

License

See LICENSE.md for license information.