How-To: Track Counts with Tag Stacks

Goal: track networked, tag-keyed counts - ammo, charges, status stacks, currencies, buildup - with a replicated FCrimsonTagStackContainer that delta-replicates only what changed.

Prerequisites

CrimsonCommon enabled, and a replicating actor or component to hold the container. This is an optional utility - nothing else in CrimsonCommon depends on it.

1. Add a replicated container

FCrimsonTagStackContainer stores a list of (GameplayTag, int32) pairs on a FFastArraySerializer, so it delta-replicates efficiently. Put one on a replicated component and mark the property Replicated - the container handles its own dirtying internally. (Use FCrimsonFloatTagStackContainer for float values like elemental buildup.)

Add a variable of type Crimson Tag Stack Container to a replicated Actor Component (set the variable to Replicated in its details), and make sure the owning actor Replicates.

Verify

The container compiles as a replicated property. (No GetLifetimeReplicatedProps entry = silent non-replication - the most common mistake.)

2. Read and modify it (server authority)

Mutate stacks on the server only; reads are safe anywhere. Blueprint uses the UCrimsonTagStackStatics library (the ref pin wires straight into your container variable); C++ calls the container methods directly.

Screenshot pendingImages/CrimsonCommon/howto-tagstack-add.png

Behind a Has Authority branch: Add Tag Stack (Container ref, Tag, Count). Read anywhere with Get Tag Stack Count.

Server authority

Only mutate tag stacks where HasAuthority() is true. A client that calls AddStack changes its local copy, which the next replication from the server silently overwrites - a classic desync bug. Route client-initiated changes through a Server_ RPC.

Verify

In a Listen Server + Client PIE test, add stacks on the server and read the same count on the client.

How-To: Track Counts with Tag Stacks

1. Add a replicated container

2. Read and modify it (server authority)

See also