Class UnityCharacterPoolService

Unity implementation of ICharacterSpawnService for characters. Owns all character pooling, instantiation, and GameObject lifecycle. Uses injected delegates for ViewModel binding to avoid circular assembly dependencies with InterfaceAdapters. Delegates receive Application-layer ICharacterConfig — no Infrastructure types leak into the bind contract. Per architecture Rule 3.3: Character module owns instantiation/pooling. It also resolves authored content to the key a character was registered under (ICharacterKeyResolver), so a wave entry naming an actor prefab spawns the registered character whose config names that prefab. And it tells a caller, with every spawn, whether a refusal was already reported (IReportingCharacterSpawner), so a wave that forfeits a refused actor does not report the same cause again.

Inheritance
object
UnityCharacterPoolService
Implements
Namespace: Serenity.Character.Infrastructure.Services
Assembly: Serenity.UnityCharacter.Infrastructure.dll
Syntax
public class UnityCharacterPoolService : MonoBehaviour, ICharacterSpawnService, IService, IFoundationSettings, ICharacterKeyResolver, IReportingCharacterSpawner

Constructors

UnityCharacterPoolService()

Declaration
public UnityCharacterPoolService()

Fields

_activeById

Maps CharacterId → PooledCharacter for fast lookup on Release.

Declaration
protected readonly Dictionary<string, UnityCharacterPoolService.PooledCharacter> _activeById
Field Value
Type Description
Dictionary<string, UnityCharacterPoolService.PooledCharacter>

_bind

Declaration
protected UnityCharacterPoolService.BindDelegate _bind
Field Value
Type Description
UnityCharacterPoolService.BindDelegate

_guid

Declaration
protected string _guid
Field Value
Type Description
string

_id

Declaration
protected string _id
Field Value
Type Description
string

_logService

Declaration
protected ILogService _logService
Field Value
Type Description
ILogService

_pool

Pool buckets keyed by prefab GetInstanceID(). Each bucket holds all instances ever created from that prefab.

Declaration
protected readonly Dictionary<int, List<UnityCharacterPoolService.PooledCharacter>> _pool
Field Value
Type Description
Dictionary<int, List<UnityCharacterPoolService.PooledCharacter>>

_rebind

Declaration
protected UnityCharacterPoolService.RebindDelegate _rebind
Field Value
Type Description
UnityCharacterPoolService.RebindDelegate

_registeredCharacters

Maps archetype key string → registered ICharacterConfig.

Declaration
protected readonly Dictionary<string, ICharacterConfig> _registeredCharacters
Field Value
Type Description
Dictionary<string, ICharacterConfig>

_unbind

Declaration
protected UnityCharacterPoolService.UnbindDelegate _unbind
Field Value
Type Description
UnityCharacterPoolService.UnbindDelegate

Properties

ActiveCount

Declaration
public int ActiveCount { get; }
Property Value
Type Description
int

Guid

Declaration
public string Guid { get; set; }
Property Value
Type Description
string

Id

Declaration
public string Id { get; set; }
Property Value
Type Description
string

LogService

Declaration
public ILogService LogService { get; set; }
Property Value
Type Description
ILogService

Methods

GetOrCreateInstance(ICharacterConfig)

Hands out a pooled instance of archetype, reusing an inactive one or instantiating its prefab; null, with the same report Spawn(string, float, float, float, float, float, float, float) writes, when the prefab is missing or has no Character View.

Declaration
protected UnityCharacterPoolService.PooledCharacter GetOrCreateInstance(ICharacterConfig archetype)
Parameters
Type Name Description
ICharacterConfig archetype
Returns
Type Description
UnityCharacterPoolService.PooledCharacter

Initialize(ILogService, BindDelegate, RebindDelegate, UnbindDelegate)

Initializes the pool service with required dependencies. Binding delegates are provided by the installer to avoid circular assembly dependencies between Infrastructure and InterfaceAdapters.

Declaration
public void Initialize(ILogService logService, UnityCharacterPoolService.BindDelegate bind, UnityCharacterPoolService.RebindDelegate rebind, UnityCharacterPoolService.UnbindDelegate unbind)
Parameters
Type Name Description
ILogService logService
UnityCharacterPoolService.BindDelegate bind
UnityCharacterPoolService.RebindDelegate rebind
UnityCharacterPoolService.UnbindDelegate unbind

OnDestroy()

Declaration
protected void OnDestroy()

RegisterCharacters(string, ICharacterConfig)

Registers a character config so the pool knows which prefab to use for the given character key. Must be called before Spawn for that key.

Declaration
public void RegisterCharacters(string archetypeKey, ICharacterConfig config)
Parameters
Type Name Description
string archetypeKey
ICharacterConfig config

Release(CharacterId)

Declaration
public void Release(CharacterId characterId)
Parameters
Type Name Description
CharacterId characterId

ReleaseAll()

Declaration
public void ReleaseAll()

ReleaseInstance(PooledCharacter)

Declaration
protected void ReleaseInstance(UnityCharacterPoolService.PooledCharacter pooled)
Parameters
Type Name Description
UnityCharacterPoolService.PooledCharacter pooled

Spawn(string, float, float, float, float, float, float, float)

Declaration
public CharacterId Spawn(string archetypeKey, float posX, float posY, float posZ, float rotX, float rotY, float rotZ, float rotW)
Parameters
Type Name Description
string archetypeKey
float posX
float posY
float posZ
float rotX
float rotY
float rotZ
float rotW
Returns
Type Description
CharacterId

TryResolveCharacterKey(object, out string)

Declaration
public bool TryResolveCharacterKey(object authoredCharacter, out string characterKey)
Parameters
Type Name Description
object authoredCharacter
string characterKey
Returns
Type Description
bool
Remarks

A registered key resolves to itself; a registered config, or the prefab one names, resolves to the key it was registered under. When several registered characters name the same prefab, the key that sorts first ordinally wins, so the answer never depends on registration order, and each character that loses is reported once as a warning naming the character that wins.

A prefab matches by object reference, which only holds where the content and the character share one loaded prefab — the editor. A build can load the same prefab as two copies from two Addressables bundles, so content that must resolve in a build names the character by its key: a wave entry carries its character's Id for exactly this reason.

TrySpawn(string, float, float, float, float, float, float, float)

Declaration
public CharacterSpawnAttempt TrySpawn(string characterKey, float positionX, float positionY, float positionZ, float rotationX, float rotationY, float rotationZ, float rotationW)
Parameters
Type Name Description
string characterKey
float positionX
float positionY
float positionZ
float rotationX
float rotationY
float rotationZ
float rotationW
Returns
Type Description
CharacterSpawnAttempt
Remarks

Every refusal is reported here before it is returned — a key nobody registered, a character without a prefab, a prefab without a Character View (once per character), a failed bind — so a caller never has to explain one again.

Implements