Multiplayer
Pulse Build is server authoritative and uses only replicated properties and RPCs (classic replication and Iris).
What runs where
| Part | Where |
|---|---|
| Aim trace, preview, placement modes, rules, cost lines | Owning client (and the listen server host) |
| Placing, removing, moving, costs, refunds, undo, construction, damage, decay, collapse | Authority |
| Building world queries, events, stability, site markers | Every machine |
Messages Pulse.Message.Build.* | Authority |
Requests
A client never adds pieces. Confirm and the Request* functions send one server RPC, Server_Request, with an FPulseBuildRequest (the definition id of the piece, transform, ids) and a request id of PulseFoundation. The request guard of PulseFoundation lets it in first (rate and open requests per player, kinds Pulse.Request.Build.Place, .Remove, .Move, …); Pulse::Build::Request::Validate then refuses requests that carry too much (more copies than MaxDragCount, more spline points than MaxRequestPoints, more extras or entry states than MaxRequestExtras, more connected ids than MaxRequestConnections, more blueprint entries than Blueprint::MaxEntries; answer Invalid) or a vector or transform that is not finite (NaN or infinity; answer Invalid Transform), before anything else is read; a piece must be named by an id of the kind PulseBuildPiece (answer Invalid Piece). The server takes only a piece it has ready (Pulse::Build::Request::ResolvePiece: registered at runtime, or in memory, which every piece of a catalog is): it never loads a path for a request, and an id it does not know is refused as Invalid Piece, also inside a blueprint (MakePieces finds, never loads). Only for a builder that may build every piece (bRequireCatalog off, free build) the server loads a piece asset the asset manager knows by the id once and keeps it (UPulseBuildComponent::FindOrLoadBuildablePiece): a dedicated server has no creative menu that would load it. Pieces a piece source allows are placeable while the server holds them (the source returns them, a catalog it has loaded, Pulse::Build::Pieces::RegisterPiece). Then the server re-runs the placement mode’s validation (ValidatePlacement), the catalog and piece sources, the range (Pulse::Requests::CheckReach, +400 cm tolerance or the larger Reach Tolerance of the request guard), the rules, the permissions and the costs. The answer, an FPulseResult, comes back to the owner through the request subsystem: OnBuildResult, GetLastResult (“Needs 4 more build points.” as its message), the callback of RequestBuildChange or the node Request Build; a failure is also sent on the client as Pulse.Message.Request.Failed, so a notification rule of the HUD can show it.
Replication of pieces
- Simple pieces live in clusters (
APulseBuildCluster, one perClusterSizearea) as a fast array ofFPulseBuildPiece. Clients receive clusters withinClusterNetCullDistance. Only changed entries are sent; a client that sees a cluster for the first time gets all of its pieces in one bunch, so a cluster holds at mostMaxPiecesPerClusterpieces (default 400, about 30 to 50 KB) and a full area gets a second cluster. - Actor pieces replicate as actors; the piece data is a replicated property of their
UPulseBuildPieceComponent. When the data arrives, the client moves the actor toPiece.Transform(world space, like the server’sSetActorTransform, so attached actors keep their parent), also for actor classes that do not replicate movement. - Both use the push model (classic replication and Iris): the cluster array is written only in
AddPiece,UpdatePieceandRemovePiece(fast array item or array dirty plus the property dirty), the piece data only inSetPiece. Debris of collapses (APulseBuildDebris) sends its look once, also push based. - What a piece is goes over the wire as
FPulseBuildPiece::DefinitionId(FPulseDefinitionId, kind and name); the pointerDefinitionisNotReplicatedand set by every machine itself (see below). - Construction progress is sent in steps (
ConstructionProgressStep) and at each payment stage, not every tick. - Health is a state only while a piece is damaged.
Clients register what they receive in their building world, so FindPiece, QueryPieces and all events work there too. A piece that moves to another cluster may arrive in either order; the subsystem ignores stale updates.
Definitions on clients
A received piece is shown and registered only once the client has its definition. Clusters and piece components hand what they receive to the building world (UPulseBuildSubsystem::SubmitReceivedPiece), which finds the definition with an FPulseDefinitionResolver of PulseFoundation: at once when it is ready (registered, in memory, or loaded at once by the catalog as replicated object pointers were), else when it arrives. Until then the piece waits; the newest state of a piece wins, and a piece that is removed, loses relevance or whose actor ends play is forgotten (CancelReceivedPiece). A piece component tells OnPieceChanged once its piece is registered.
An id no definition answers to (a piece the client does not have, a runtime piece not registered there) leaves the piece waiting: the log warns once per id, and the debug snapshot of the building world counts “Pieces waiting for definition” and “Pieces with missing definition” (GetNumPiecesWaitingForDefinition, GetNumPiecesWithMissingDefinition, also printed by PulseBuildInfo). When the definitions of pieces change (a definition registered after the replication), the waiting pieces are tried again. There is no time limit. On the server and a listen host every placed piece is resolved already; nothing waits there.
Dormant clusters
With bDormantClusters clusters go dormant after they reached the clients and wake up only for their own changes (placing, removing, construction progress). Idle clusters then cost the server nothing, also with thousands of them. The catch: dormant actors are no longer checked for distance, so clients keep every cluster they have received, also far away. Use it for servers with many clusters in a limited map; leave it off for very large or endless worlds, where distance culling keeps the clients small.
Load test
PulseBuildStress <piece> <count> adds pieces in rows for load tests. Measured in the editor (listen server + client in one process, test level): 2000 walls are added on the server in about 50 ms and form 8 clusters; the client receives all of them. Afterwards the frame costs about 1 ms more on the GPU and about 2 ms more on the game thread for both worlds together (with dormant clusters the game thread cost drops to the level without walls). Right after adding that many instances the first seconds are slow while the scene is rebuilt.
Owner data
Build points, the undo and redo counts and the piece the player works on replicate to the owner only, as one struct (FPulseBuildBuilderNetState, GetNetState()) with the push model: every change goes through the component (AddBuildPoints, SetBuildPoints, work, history), never a direct write. Hotbar, favorites and recent pieces are local to the owning machine plus the server copy used for saving.
Zones
A zone actor replicates one struct, FPulseBuildZoneNetState (type, claim owner, piece limit, extent), with the push model and a notify on every receive; zones are always relevant. Every write goes through SetupZone, SetPieceLimit or BeginPlay (the box size), never a direct field write. Zones placed in the level start from their authored values on server and clients; zones spawned at runtime start from the struct default on clients, which is the replication baseline, so the server sends every value it holds differently. Priority, allowed pieces, display name and decay prevention are not replicated (level values).
Zones sleep on the network (net dormancy), because they change only when a claim or its limit changes: a placed zone is not sent until it changes, a spawned one sleeps after its first replication, and every write wakes it once (FlushNetDormancy in the write).
Testing
Use PIE with a listen server and a client in /PulseBuild/Examples/LV_PulseBuildExample. Pulse.PIE.Exec 1 <cmd> (PulseFoundation) runs a cheat as the client player; the cheats that change the world forward themselves to the server.