Add a system for modifying entity names without causing conflicts (#27863)

Content.Shared/NameModifier/Components/ModifyWearerNameComponent.cs

@@ -0,0 +1,25 @@
+using Robust.Shared.GameStates;
+
+namespace Content.Shared.NameModifier.Components;
+
+/// <summary>
+/// Adds a modifier to the wearer's name when this item is equipped,
+/// and removes it when it is unequipped.
+/// </summary>
+[RegisterComponent, NetworkedComponent]
+[AutoGenerateComponentState]
+public sealed partial class ModifyWearerNameComponent : Component
+{
+    /// <summary>
+    /// The localization ID of the text to be used as the modifier.
+    /// The base name will be passed in as <c>$baseName</c>
+    /// </summary>
+    [DataField, AutoNetworkedField]
+    public LocId LocId = string.Empty;
+
+    /// <summary>
+    /// Priority of the modifier. See <see cref="EntitySystems.RefreshNameModifiersEvent"/> for more information.
+    /// </summary>
+    [DataField, AutoNetworkedField]
+    public int Priority;
+}

Content.Shared/NameModifier/Components/NameModifierComponent.cs

@@ -0,0 +1,20 @@
+using Content.Shared.NameModifier.EntitySystems;
+using Robust.Shared.GameStates;
+
+namespace Content.Shared.NameModifier.Components;
+
+/// <summary>
+/// Used to manage modifiers on an entity's name and handle renaming in a way
+/// that survives being renamed by multiple systems.
+/// </summary>
+[RegisterComponent]
+[NetworkedComponent, AutoGenerateComponentState]
+[Access(typeof(NameModifierSystem))]
+public sealed partial class NameModifierComponent : Component
+{
+    /// <summary>
+    /// The entity's name without any modifiers applied.
+    /// </summary>
+    [DataField, AutoNetworkedField]
+    public string BaseName = string.Empty;
+}

Content.Shared/NameModifier/EntitySystems/ModifyWearerNameSystem.cs

@@ -0,0 +1,34 @@
+using Content.Shared.Clothing;
+using Content.Shared.Inventory;
+using Content.Shared.NameModifier.Components;
+
+namespace Content.Shared.NameModifier.EntitySystems;
+
+public sealed partial class ModifyWearerNameSystem : EntitySystem
+{
+    [Dependency] private readonly NameModifierSystem _nameMod = default!;
+
+    public override void Initialize()
+    {
+        base.Initialize();
+
+        SubscribeLocalEvent<ModifyWearerNameComponent, InventoryRelayedEvent<RefreshNameModifiersEvent>>(OnRefreshNameModifiers);
+        SubscribeLocalEvent<ModifyWearerNameComponent, ClothingGotEquippedEvent>(OnGotEquipped);
+        SubscribeLocalEvent<ModifyWearerNameComponent, ClothingGotUnequippedEvent>(OnGotUnequipped);
+    }
+
+    private void OnGotEquipped(Entity<ModifyWearerNameComponent> entity, ref ClothingGotEquippedEvent args)
+    {
+        _nameMod.RefreshNameModifiers(args.Wearer);
+    }
+
+    private void OnGotUnequipped(Entity<ModifyWearerNameComponent> entity, ref ClothingGotUnequippedEvent args)
+    {
+        _nameMod.RefreshNameModifiers(args.Wearer);
+    }
+
+    private void OnRefreshNameModifiers(Entity<ModifyWearerNameComponent> entity, ref InventoryRelayedEvent<RefreshNameModifiersEvent> args)
+    {
+        args.Args.AddModifier(entity.Comp.LocId, entity.Comp.Priority);
+    }
+}

Content.Shared/NameModifier/EntitySystems/NameModifierSystem.cs

@@ -0,0 +1,143 @@
+using System.Linq;
+using Content.Shared.Inventory;
+using Content.Shared.NameModifier.Components;
+
+namespace Content.Shared.NameModifier.EntitySystems;
+
+/// <inheritdoc cref="NameModifierComponent"/>
+public sealed partial class NameModifierSystem : EntitySystem
+{
+    [Dependency] private readonly MetaDataSystem _metaData = default!;
+
+    public override void Initialize()
+    {
+        base.Initialize();
+
+        SubscribeLocalEvent<NameModifierComponent, EntityRenamedEvent>(OnEntityRenamed);
+    }
+
+    private void OnEntityRenamed(Entity<NameModifierComponent> entity, ref EntityRenamedEvent args)
+    {
+        SetBaseName((entity, entity.Comp), args.NewName);
+        RefreshNameModifiers((entity, entity.Comp));
+    }
+
+    private void SetBaseName(Entity<NameModifierComponent> entity, string name)
+    {
+        if (name == entity.Comp.BaseName)
+            return;
+
+        // Set the base name to the new name
+        entity.Comp.BaseName = name;
+        Dirty(entity);
+    }
+
+    /// <summary>
+    /// Raises a <see cref="RefreshNameModifiersEvent"/> to gather modifiers and
+    /// updates the entity's name to its base name with modifiers applied.
+    /// This will add a <see cref="NameModifierComponent"/> if any modifiers are added.
+    /// </summary>
+    /// <remarks>
+    /// Call this to update the entity's name when adding or removing a modifier.
+    /// </remarks>
+    public void RefreshNameModifiers(Entity<NameModifierComponent?> entity)
+    {
+        var meta = MetaData(entity);
+        var baseName = meta.EntityName;
+        if (Resolve(entity, ref entity.Comp, logMissing: false))
+            baseName = entity.Comp.BaseName;
+
+        // Raise an event to get any modifiers
+        // If the entity already has the component, use its BaseName, otherwise use the entity's name from metadata
+        var modifierEvent = new RefreshNameModifiersEvent(baseName);
+        RaiseLocalEvent(entity, ref modifierEvent);
+
+        // Nothing added a modifier, so we can just use the base name
+        if (modifierEvent.ModifierCount == 0)
+        {
+            // If the entity doesn't have the component, we're done
+            if (entity.Comp == null)
+                return;
+
+            // Restore the base name
+            _metaData.SetEntityName(entity, entity.Comp.BaseName, meta, raiseEvents: false);
+            // The component isn't doing anything anymore, so remove it
+            RemComp<NameModifierComponent>(entity);
+            return;
+        }
+        // We have at least one modifier, so we need to apply it to the entity.
+
+        // Get the final name with modifiers applied
+        var modifiedName = modifierEvent.GetModifiedName();
+
+        // Add the component if needed, and initialize it with the base name
+        if (!EnsureComp<NameModifierComponent>(entity, out var comp))
+            SetBaseName((entity, comp), meta.EntityName);
+
+        // Set the entity's name with modifiers applied
+        _metaData.SetEntityName(entity, modifiedName, meta, raiseEvents: false);
+    }
+}
+
+/// <summary>
+/// Raised on an entity when <see cref="NameModifierSystem.RefreshNameModifiers"/> is called.
+/// Subscribe to this event and use its methods to add modifiers to the entity's name.
+/// </summary>
+[ByRefEvent]
+public sealed class RefreshNameModifiersEvent : IInventoryRelayEvent
+{
+    /// <summary>
+    /// The entity's name without any modifiers applied.
+    /// If you want to base a modifier on the entity's name, use
+    /// this so you don't include other modifiers.
+    /// </summary>
+    public readonly string BaseName;
+
+    private readonly List<(LocId LocId, int Priority, (string, object)[] ExtraArgs)> _modifiers = [];
+
+    /// <inheritdoc/>
+    public SlotFlags TargetSlots => ~SlotFlags.POCKET;
+
+    /// <summary>
+    /// How many modifiers have been added to this event.
+    /// </summary>
+    public int ModifierCount => _modifiers.Count;
+
+    public RefreshNameModifiersEvent(string baseName)
+    {
+        BaseName = baseName;
+    }
+
+    /// <summary>
+    /// Adds a modifier to the entity's name.
+    /// The original name will be passed to Fluent as <c>$baseName</c> along with any <paramref name="extraArgs"/>.
+    /// Modifiers with a higher <paramref name="priority"/> will be applied later.
+    /// </summary>
+    public void AddModifier(LocId locId, int priority = 0, params (string, object)[] extraArgs)
+    {
+        _modifiers.Add((locId, priority, extraArgs));
+    }
+
+    /// <summary>
+    /// Returns the final name with all modifiers applied.
+    /// </summary>
+    public string GetModifiedName()
+    {
+        // Start out with the entity's name name
+        var name = BaseName;
+
+        // Iterate through all the modifiers in priority order
+        foreach (var modifier in _modifiers.OrderBy(n => n.Priority))
+        {
+            // Grab any extra args needed by the Loc string
+            var args = modifier.ExtraArgs;
+            // Add the current version of the entity name as an arg
+            Array.Resize(ref args, args.Length + 1);
+            args[^1] = ("baseName", name);
+            // Resolve the Loc string and use the result as the base in the next iteration.
+            name = Loc.GetString(modifier.LocId, args);
+        }
+
+        return name;
+    }
+}