Extending Pulse Build

Every extension point is an instanced struct (C++) or a Blueprint handler. Extensions keep no per-player state; what they need comes in a context.

Extension Base Blueprint Context
Cost FPulseCost (PulseFoundation) UPulseCostObject via Blueprint Cost FPulseCostContext + FPulseBuildCostExtra
Rule FPulseBuildRule Pulse conditions via Conditions FPulseBuildRuleContext
Permission FPulseBuildPermission UPulseBuildPermissionHandler via Custom (Blueprint) FPulseBuildPermissionContext
Placement mode FPulseBuildPlacementMode (C++) FPulseBuildPlacementInput
Spline shaper FPulseBuildSplineShaper (in Shapers of the Spline trait) (C++) FPulseBuildSplineShapeContext
Piece trait FPulseBuildPieceTrait (data only)  
Piece state FPulseBuildPieceState (C++)  
Piece source FPulseBuildPieceSource (C++) the build component

For rules that go beyond these, replace the construction, zone or integrity subsystem with a class of your own (Replacing and switching off subsystems).

Costs

Building costs are the Pulse costs of PulseFoundation, so a new cost works for pieces and in the cost lists of every other Pulse plugin. Derive from FPulseCost and override:

  • CanPay(Context): client preview and server; Passed, Failed, or Unknown when this machine cannot know.
  • Pay(Context): authority, after every cost of the payment can pay. Return false to roll the payment back.
  • Refund(Context): removals, cancelled sites, undo, rollbacks. Without a Player (destroyed pieces) drop it at Context.Location in the world of Pulse::Conditions::FindWorld(Context), or ignore it.
  • GetDisplayText(Context) and GetLines(Context, OutLines): label, icon, have and need for the UI. The preview turns the first line the player cannot pay into “Needs 4 more Wood.”.

Turn amounts into integers with Pulse::Costs::GetAmount(Amount, Context, bPaying). It applies Fraction (pieces, length, stage, refund part), Offset (stages paid before) and the rounding direction (bReverse for undo and rollbacks), so stages add up and undo never creates or loses resources. What a building cost needs beyond the context is in its extra: Pulse::Build::Construction::GetCostExtra(Context) (build component, piece definition, tier, piece id) and GetCostBuilder(Context) (the build component of the payment, else the one of the player).

Rules

Derive from FPulseBuildRule, override Check(Context) and optionally GetPreviewTint (the integrity rule colors the preview this way). Rules run on the client for the preview and on the server. Check answers with an FPulseResult:

  • FPulseResult::Success() when the piece may stand there;
  • a reason of Pulse Build: Pulse::Build::ToResult(EPulseBuildResult::TooClose);
  • a reason of your game: FPulseResult::Failure(YourReason), with its text registered once in StartupModule (Pulse::Results::RegisterReason), so a project can replace it in Project Settings > Pulse > Foundation > Result Texts. Set the message only for the text of a single case (“Only 3 per player.”).

A failure without a reason counts as Pulse.Result.Failure.Build.RuleFailed. The preview (FPulseBuildPlacement::Result) and the answer of the request carry the result as it is; the code of the preview (EPulseBuildResult, the view model’s PlacementResult) is RuleFailed for reasons of others. Checks of the player (a skill, an item, a quest, a team) need no C++: the Conditions rule takes Pulse conditions, also Blueprint conditions (see Placement and rules).

Permissions

Derive from FPulseBuildPermission and override Check(Context): it answers with an FPulseResult like a rule, usually Pulse::Build::ToResult(EPulseBuildResult::NotAllowed) or a reason of your game; a failure without a reason counts as NotAllowed. Blueprint handlers implement Check Permission and return Make Pulse Success or Make Pulse Failure (the reason, and a message for a single case). To give players the rights of an owner’s team (a party, friends, a guild), add a check to Pulse::Build::OnCheckOwnerGroup() instead: it gets the world, the owner and the player and sets bInOutInGroup; the permission Owner and Team, claims and decay ask it on the server and in client previews. The context has the builder, the player’s owner data (Player), the action and the piece (or the new piece). Add it to DefaultPermissions in the settings.

The zone rule itself is a set of pure functions in Pulse::Build::Zones (CheckAction on an FPulseBuildZoneQuery). A tool can run it on a query of its own (a planner, an editor check): fill every input the NeedsPieceCount, NeedsPlayerPieceCount and NeedsClaims functions ask for, or start from UPulseBuildZoneSubsystem::MakeQuery; a missing input refuses the action.

Placement modes

Derive from FPulseBuildPlacementMode: ComputePlacement (client, from the aim; sets the Result of the placement when there is no place) and ValidatePlacement (server, for a transform a client sent; answers with an FPulseResult, for example Pulse::Build::ToResult(EPulseBuildResult::InvalidTransform)). Use the math in Pulse::Build::Math (AttachToSocket, SnapToGrid, oriented boxes).

Traits and states

Traits (FPulseBuildPieceTrait) are data on definitions; read them with Definition->FindTrait<T>(). To find the pieces with a trait near a place (heat sources around a player, workbenches in reach) use Pulse::Build::QueryPiecesWithTrait<T>(Subsystem or world context, Center, Radius, Out): each piece in the sphere (by its bounds) with its trait, in one pass over the index with the trait looked up once per definition, cheaper than QueryPieces plus FindTrait per piece. UPulseBuildSubsystem::QueryPiecesWithTrait(TraitType, ...) takes the struct (base types find derived traits too), and Blueprint has Query Pieces With Trait. States (FPulseBuildPieceState) are runtime data of a piece, replicated with it: ShouldSave (into save data) and ShouldCopy (into blueprints). Change states on the authority with UPulseBuildSubsystem::UpdatePiece; use Pulse::Structs::SetUniqueByType to keep one per type.

Piece sources

Derive from FPulseBuildPieceSource: GetPieces(Builder, OutPieces) for the menu and CanBuild(Builder, Piece) for the checks. Add it to DefaultPieceSources (settings), register it with Pulse::Build::Registry::RegisterPieceSource (bridges, see below) or add it to PieceSources (component). Good for unlocks by skills or quests and for items (build kits). Sources keep no state: when what a source offers changes, call NotifyAvailablePiecesChanged on the build component (on every machine that shows a build menu), so the menu updates.

Tuning adjustments

Difficulty levels, events and rewards change single pieces through the adjustments of the tuning of PulseFoundation: Piece Costs, Lock Piece and Piece Decay (see Construction). They need no code: add them to the Adjustments of a tuning source or a UPulseTuningPreset. Game code that computes costs itself reads them with the pure functions of Pulse::Build::Adjustments (GetEffectiveCosts, IsPieceLocked, GetDecayPerHour) on Pulse::Adjustments::GetData of its world, and keeps what it paid with Construction::RecordPayment so refunds give back the same.

Bridges

Bridges plug in from outside, without changes to Pulse Build:

  • Pulse::Build::Registry (PulseBuildRegistry.h): piece sources, default rules, cluster components and the cluster class, registered at runtime (see Registering at runtime);
  • UPulseBuildSettings::ClusterClass and ClusterComponentClasses: what the project chose for clusters (the base the registry adds to);
  • UPulseBuildSubsystem events, OnSaveExtras / OnLoadExtras, OnSavePieceActor / OnLoadPieceActor, IsClearingPieces, OnSaveDataAppliedNative (saved data in place);
  • Pulse::Build::Blueprint::OnCaptureEntryNative(): data of the bridge in captured blueprints (Blueprints); OnBlueprintPlacementStartedNative / OnBlueprintPlacedNative (which pieces form one blueprint);
  • OnPieceEndedNative: whether a piece was really removed (Removed), cleared (RemoveAllPieces, loading) or only unregistered (replication, a destroyed actor); demolish what belongs to a piece only on Removed;
  • UPulseBuildConstructionSubsystem::IsUpkeepPaid (decay) and its events;
  • UPulseBuildIntegritySubsystem::IsGroundedOverride;
  • messages Pulse.Message.Build.* for loose reactions (quests, achievements, statistics).

Registering at runtime

Bridges do not write UPulseBuildSettings. They register what they add with Pulse::Build::Registry and take it back when they go, so the settings stay what the project chose:

// StartupModule (or when a subsystem initializes)
Pulse::Build::Registry::RegisterPieceSource(TEXT("MyBridge"), FInstancedStruct::Make(FMyPieceSource()));
Pulse::Build::Registry::RegisterRule(TEXT("MyBridge"), FInstancedStruct::Make(FMyRule()));
Pulse::Build::Registry::RegisterClusterComponent(TEXT("MyBridge"), UMyClusterComponent::StaticClass());
Pulse::Build::Registry::RegisterClusterClass(TEXT("MyBridge"), AMyCluster::StaticClass());

// ShutdownModule (or Deinitialize)
Pulse::Build::Registry::Unregister(TEXT("MyBridge"));
Function What it does
RegisterPieceSource(Owner, Source), UnregisterPieceSources(Owner) Piece sources for every builder, after the settings’ DefaultPieceSources; the build components are told at once (NotifyAvailablePiecesChanged)
RegisterRule(Owner, Rule), UnregisterRules(Owner) Default rules, after the settings’ DefaultRules; pieces with bUseDefaultRules off skip them
RegisterClusterComponent(Owner, Class), UnregisterClusterComponents(Owner) Components of clusters spawned afterwards, after the settings’ ClusterComponentClasses
RegisterClusterClass(Owner, Class), UnregisterClusterClass(Owner) The cluster class while the settings’ ClusterClass is empty; the first owner that registers one counts
Unregister(Owner), IsRegistered(Owner) Everything of an owner
ForEachDefaultRule, ForEachPieceSource, GetClusterComponentClasses, GetClusterClass, HasDefaultRule(Type), HasPieceSource(Type) What Pulse Build reads: the settings, then the registered entries
OnChanged() After any registration changed

The settings are the base list. A registered piece source or rule whose struct type the settings already hold is left out, and so is a registered component class the settings list, so a project that keeps the entry in its settings (from an older bridge that wrote them) does not get it twice. Registering a source or rule of a type the owner registered before replaces it. The registry is global (all worlds), runs on the game thread, keeps the objects its structs point to and is cleared when the module of Pulse Build shuts down. Switch an entry off at runtime (a setting of the bridge changed) with the matching Unregister call.

Migration note: bridges that still write the settings

Before the registry, bridges added their entries to UPulseBuildSettings (at module startup or in an editor setup step that saved DefaultGame.ini). These bridges switch to Pulse::Build::Registry (and drop the setup steps that wrote the settings of Pulse Build):

Bridge State
PulseBuildFactionTerritoryBridge Switched: registers the rule Own Faction Territory (RegisterRule) while its setting bRegisterTerritoryRule is on; its editor step no longer writes DefaultRules
PulseBuildGameplayBridge (modules Combat, HUD and Inventory) Switched: Combat registers the damageable cluster class (RegisterClusterClass, bDamageableClusters), HUD the site interaction component (RegisterClusterComponent, bHoldToBuild), Inventory the piece source Inventory Build Kits (RegisterPieceSource, bAddBuildKitSource); the Inventory save handlers for actor pieces are gone, Pulse Build saves the chests itself
PulseBuildSkillBridge Switched: registers the piece source Skills (RegisterPieceSource) while its setting bAddSkillPieceSource is on
PulseFactoryBuildBridge Switched: registers its piece sources and rules through the registry
PulseNavBuildBridge Nothing to switch: it has no settings entries; its example door saves itself as an IPulseByteSaveable (Pulse.NavBuild.Save.ExampleDoor), and OnLoadPieceActor stays only to read old saves

Projects that already hold an entry of such a bridge in their settings (written by an older version) keep working: a registered entry whose type the settings hold is left out, so nothing counts twice. Remove the entry from the settings once the bridge registers it, unless the project wants other values than the bridge’s.


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