Core concepts

Pieces

A piece definition (UPulseBuildPieceDefinition, primary asset type PulseBuildPiece) describes a kind of piece: mesh or actor class, bounds, placement mode, sockets, rules and traits (instanced structs for costs, construction, health, tiers, integrity, claims, splines, and whatever other plugins add).

A piece (FPulseBuildPiece) is one placed instance: a stable Id (GUID), the definition (its id DefinitionId, which replicates and is saved, and the Definition each machine finds for it, see Pieces), a transform, an owner (FPulseBuildOwner: player id and team), a tier and runtime states (construction progress, health, spline points).

  • Simple pieces have only a mesh. They are drawn as instances of instanced static mesh components inside clusters (APulseBuildCluster), one cluster per area (ClusterSize). Thousands of walls cost a handful of actors.
  • Actor pieces have an ActorClass (door, chest, machine). The actor is spawned with a UPulseBuildPieceComponent that carries the piece data.

Both kinds have the same id, owner, states and events.

The building world

UPulseBuildSubsystem (world subsystem, on every machine) knows every piece of the world, with a grid index for area queries. The authority adds, changes and removes pieces; clusters and piece actors replicate them, and clients register what they receive. So the same queries (FindPiece, QueryPieces, GetPiecesInRadius, FindPieceIdFromHit) work on server and clients, and the preview can check sockets and overlaps locally. A query whose box spans more index cells than there are pieces (a huge radius) tests the pieces one by one instead of walking the grid, pieces too large for the index (over 4096 cells) are kept aside and tested by every query, and a negative or NaN radius finds nothing, an infinite one every piece.

Events (OnPieceAdded, OnPieceChanged, OnPieceRemoved, native and Blueprint) fire on every machine. Messages on the PulseFoundation message bus (Pulse.Message.Build.Placed, .Removed, .Changed, .Completed, .Upgraded, .Damaged, .Repaired, .Destroyed, .Collapsed) are sent on the authority, for quests, achievements and statistics that should not need a bridge.

Builders

UPulseBuildComponent is the player’s builder. Locally it keeps the tool (Place, Remove, Move, Rotate, Pipette, Copy, PlaceBlueprint, Upgrade, Repair, Work), the selected piece, the aim trace and the ghost preview (APulseBuildPreview). Actions become requests (FPulseBuildRequest with a request id of PulseFoundation); the server runs the same checks again and answers with an FPulseResult: success, or the reason with its text (OnBuildResult, GetLastResult, the callback of RequestBuildChange).

How placing works

  1. The placement mode computes a transform from the aim (ComputePlacement): free, grid cell, socket or spline.
  2. The rules check it (overlap, slope, surface, support, limits, distance, stability, …).
  3. Permissions check it (owner, team, claims, zones, piece limits).
  4. Costs are checked (CanPay) so the preview can show what is missing.
  5. On confirm the client sends the transform. The server validates the mode (ValidatePlacement), the catalog, the range, rules, permissions, pays the costs (all or nothing) and adds the piece.
  6. With a Construction trait the piece starts as a construction site; it finishes after its build time.

Systems on top

System Where Page
Construction, costs, tiers, health, decay UPulseBuildConstructionSubsystem (authority) Construction
Structural integrity UPulseBuildIntegritySubsystem (every machine; collapse on the authority) Integrity
Zones, claims, limits UPulseBuildZoneSubsystem, APulseBuildZone Permissions and zones
UI UPulseBuildUISubsystem (local player), UMVVMPulseBuilder UI

Replacing and switching off subsystems

Three subsystems of Pulse Build are overridable: a class of your game derived from one of them replaces it, with rules of your own. How replacing works in general: Replacing and switching off subsystems of Pulse Foundation.

Subsystem Override For
UPulseBuildConstructionSubsystem (authority) AddWork, AdvanceSites, TickDecay, ApplyDamage, Repair Your own construction progress, decay, damage and repair.
UPulseBuildZoneSubsystem (every machine) CheckAction, MakeQuery, CountPieces Your own building rights.
UPulseBuildIntegritySubsystem (every machine) ComputePlacementStability, MakeNode, IsGrounded, Collapse, SpawnDebris Your own statics.
  • Write the class in C++ in a module loaded in the phase Default or earlier. It answers true in ShouldCreateSubsystem through Super (game worlds only, like the base); the base is then not created.
  • Callers keep asking for the base: UPulseBuildConstructionSubsystem::Get and the other Get functions give your class, and the zones and the integrity subsystem bind to your construction subsystem.
  • Zones and integrity run on every machine: the replacement must be in the game on clients too.
  • None of them is switchable: placing, permissions and upkeep build on them. Disabled Subsystems of Pulse Foundation does not turn them off (the settings warn about such an entry). Integrity computes nothing without pieces that have the Integrity trait.
  • Smaller changes need no replacement: costs, rules, permissions and the decay upkeep hook (IsUpkeepPaid) are extension points (Extending Pulse Build).
UCLASS()
class UMyConstructionSubsystem : public UPulseBuildConstructionSubsystem
{
	GENERATED_BODY()

public:

	// No decay while the owner is online
	virtual int32 TickDecay(float InHours) override
	{
		return IsAnyOwnerOnline() ? 0 : Super::TickDecay(InHours);
	}

private:

	bool IsAnyOwnerOnline() const;
};

Specs: PulseBuild.Subsystems, PulseBuild.Integrity.Subsystems.

Debugging

The building world, the construction subsystem and the integrity subsystem are snapshot providers of PulseFoundation: their state shows on the Pulse Debugger’s live page, in the gameplay debugger category “Pulse” and with PulseDebugDump Build. Placements, removals and construction steps are timeline events. Pulse.Build.Debug 1 draws sockets and bounds near the player.


This site uses Just the Docs, a documentation theme for Jekyll.