Infrastructure runtime et utils Unity

Dossier

Assets/Src/Utils/ contient l'infrastructure Unity qui ne relève pas directement d'un domaine métier.

CommandManager

CommandManager.cs est un gestionnaire historique des commandes GameSparks. Sa méthode SendCommand() refuse l'appel si le backend courant n'est pas eGameSparks. La voie BrainCloud moderne passe par BackEndBrainCloud.SendCommand(); ne pas confondre les deux systèmes.

Événements locaux vs RTT

flowchart LR
LOCAL[GameEventMessageUtils] --> UI[UI / transitions locales]
SERVER[BrainCloud RTT] --> DISPATCH[MessagesDispatcher]
DISPATCH --> CTRL[Controllers]
CTRL --> UI

Un événement UI local n'est pas une synchronisation serveur. Pour une feature multi-utilisateur, il faut généralement persister côté serveur puis recevoir un message RTT.

Règle de maintenance

Éviter d'ajouter de grosses règles métier dans Utils.cs. Une fonction Accounting, MK1, HR1, etc. doit vivre avec son domaine. Le dossier Utils doit rester transversal.

Carte réelle de l’infrastructure runtime

Composition dans Game.Awake()

Game est le composition root principal. Il initialise notamment :

• PoolsManager depuis une référence sérialisée;
• Scheduler = new Scheduler();
• MessagesDispatcher = new MessagesDispatcher();
• FxMgr, CommandManager, Toaster;
• NotificationManager;
• TextsManager;
• la machine d’état via ContextScheduledMachine<GameStateDTO>.

Game.Update() appelle Scheduler.Update(); Game.LateUpdate() appelle Scheduler.LateUpdate(). Un service enregistré au Scheduler n’a donc pas besoin de son propre MonoBehaviour.Update().

Ajouter un service runtime global de A à Z

Ne rendre un service global que s’il doit réellement exister une seule fois pendant toute la session. Un service propre à une simulation, équipe ou popup doit rester dans son controller/contexte.

1. Choisir MonoBehaviour ou classe pure

• classe pure : pas besoin de scene lifecycle, inspector ou coroutine;
• MonoBehaviour : dépend de références Unity sérialisées, coroutines, callbacks Unity ou scene objects.

2. Ajouter la propriété dans Game seulement si elle est globale

public static MyService MyService { get; private set; }

Pour une classe pure, l’instancier dans Game.Awake(). Pour un MonoBehaviour, injecter une référence sérialisée depuis la scène/prefab puis assigner la propriété.

3. Définir explicitement son lifecycle

Décider :

• quand il est initialisé;
• s’il dépend de Backend ou de CurrentGameUid;
• ce qui doit être reset lors d’un changement de simulation;
• ce qui doit être nettoyé dans OnDestroy() ou logout.

4. Ne pas créer un deuxième singleton caché

Si le service est déjà accessible via Game, éviter un second static Instance sauf raison Unity spécifique. Les doubles singletons rendent les tests et changements de scène difficiles à tracer.

5. Tester relog / changement de jeu

Un service global qui garde une référence au vieux TeamController, à une ancienne simulation ou à un prefab détruit produit des bugs fantômes. Tester au minimum : login → simulation A → logout/reload → simulation B.

Scheduler — ordonnancement par priorité

Les priorités sont exécutées dans cet ordre :

BeginFrame
ServerEvent
Fsm
World
Render
Ui
EndFrame

Le même ordre existe pour le registry de LateUpdate.

Ajouter un callback planifié

Game.Scheduler.Register(
    Scheduler.Priority.Ui,
    UpdateMyControl
);

// nettoyage obligatoire
Game.Scheduler.Unregister(
    Scheduler.Priority.Ui,
    UpdateMyControl
);

Scheduler.Unregister() sait gérer une désinscription pendant qu’une priorité est en cours d’itération : le callback est placé dans _toRemove puis retiré après la boucle. Il faut néanmoins utiliser exactement le même delegate lors du unregister.

ScheduledMachine

ScheduledMachine.Start() s’enregistre automatiquement dans la priorité Fsm pour Update et LateUpdate. Stop() se désenregistre puis déclenche onStop. C’est la raison pour laquelle la machine d’état principale n’a pas son propre MonoBehaviour.Update().

Coroutiner — lancer une coroutine hors MonoBehaviour

Game.Instance.coroutiner sert de point d’ancrage lorsque le code appelant n’est pas lui-même un MonoBehaviour :

Coroutine c = Game.Instance.coroutiner.StartLocalCoroutine(
    MyRoutine()
);

// si nécessaire
Game.Instance.coroutiner.StopLocalCoroutine(c);

Ne pas laisser une coroutine continuer après destruction logique de son owner. Si elle modifie un popup/controller qui peut disparaître, conserver la référence et l’arrêter au teardown.

ObjectPool et PoolsManager

ObjectPool<T> possède deux modes :

• local pool — défaut actuel : le template et les instances restent gérés par le pool local;
• global PoolsManager — isLocalPool = false : le template est enregistré par son Type dans Game.PoolsManager.

Créer un objet poolable

public class MyRow : PoolableObject
{
    public override void Alloc()
    {
        // remettre l’état nécessaire pour une nouvelle utilisation
    }

    public override void Free()
    {
        // retirer listeners, vider données temporaires, arrêter tweens
    }
}

Utilisation

_pool = new ObjectPool<MyRow>(rowTemplate, contentRoot);

MyRow row = _pool.AllocTemplate();
row.SetData(data);

// plus tard
_pool.FreeTemplate(row);
// ou
_pool.FreeAllTemplates();

Règle critique

Free() doit remettre l’objet dans un état réutilisable. Un pool masque facilement des bugs de lifecycle : listener ajouté à chaque Alloc(), tween encore actif, référence à l’ancien modèle, event global non retiré.

GameEventMessageUtils vs RTT vs Action locale

GameEventMessageUtils contient par exemple les événements de tabs, login/scenario/choose team et quelques événements By Module/MK. Ce bus ne persiste rien et ne traverse pas le réseau.

Extensions.Fire() et diagnostic des callbacks

Les extensions Action.Fire() ne sont pas de simples ?.Invoke() : elles parcourent la liste des delegates et encadrent chaque appel avec CrashMessages.CrashMessage.StackPush/StackPop. Cela permet de conserver plus de contexte lorsqu’un callback plante.

Pour les events existants qui utilisent ce pattern, préférer .Fire() afin de conserver ce diagnostic.

Temps : GlobalTime, UtilsBase et temps serveur

GlobalTime.UtcNow retourne actuellement directement DateTime.UtcNow converti en epoch ms. L’ancien mécanisme de resynchronisation périodique serveur est commenté.

En parallèle, Game.RefreshCurrentServerTime() charge explicitement l’heure via le backend et Game.Update() fait avancer currentServerTime.

Donc, pour une règle métier sensible au serveur, ne pas supposer que GlobalTime.UtcNow est une horloge serveur synchronisée.

Où placer un nouvel helper

CommandManager : ne pas l’utiliser pour BrainCloud

CommandManager.SendCommand() accepte des GSTypedRequest et vérifie explicitement que Game.Backend.BackEndType == eGameSparks. Il gère l’ancien throttling GameSparks et le loading circle.

Une nouvelle feature BrainCloud doit passer par BackEndBrainCloud.SendCommand() / les méthodes de BackEndBase, jamais par CommandManager.

Checklist avant d’ajouter une nouvelle infrastructure

• Le besoin est-il vraiment global ?
• Peut-il vivre dans un controller existant ?
• Le lifecycle de cleanup est-il défini ?
• Scheduler plutôt qu’un Update supplémentaire ?
• Coroutine arrêtée si owner détruit ?
• Pool : Alloc()/Free() symétriques ?
• Event local ou RTT correctement choisi ?
• Helper placé dans le bon domaine plutôt que dans Utils.cs ?
• Aucune dépendance GameSparks introduite dans une nouvelle feature BrainCloud ?
• Relog/changement de simulation testé ?

Debug rapide