Construction

Pieces can cost something, take time to build, have health, upgrade through tiers and decay. UPulseBuildConstructionSubsystem runs all of it on the authority; clients see the results through replication.

Costs

The Costs trait (FPulseBuildPieceTrait_Costs) holds the costs of tier 0: the Pulse costs of PulseFoundation (FPulseCost), the same entries skills, dialogs and recipes use. Every cost of the project can be picked:

Cost Plugin Pays with
Build Points PulseBuild The build points of UPulseBuildComponent (NetState.BuildPoints, replicated to the owner; AddBuildPoints and SetBuildPoints on the authority). Works in every Pulse cost list, e.g. a skill rank that costs build points
Items PulseGameplay Items of the player’s inventory, by item or tag; refunds go back into it, the rest drops as pickups
Blueprint Cost PulseFoundation A UPulseCostObject Blueprint: CanPay, Pay, Refund, GetDisplayText
Skill Points, Attribute, … other Pulse plugins Whatever they pay with
Property Meaning
bScaleWithLength, LengthUnit Spline pieces pay per length unit
RefundFraction Part of the value a finished piece gives back when removed (default 0.5)
PaymentStages 1: everything at placing. More: a construction site pays in parts while it is built
RepairCostFraction Part of the value a full repair costs, scaled by the missing health

A payment is all or nothing: when one cost fails after others were paid, those are given back. Integer amounts are rounded over the whole cost (payments up, refunds down), so payment stages add up to exactly the full cost.

Costs go through the tuning knob Pulse.Tuning.Cost of PulseFoundation, with the kind Pulse.CostKind.Build (placing, upgrading, the stages of sites) or Pulse.CostKind.Repair (repairs) in the tags, so a difficulty makes building dearer or cheaper. Cost adjustments change the costs of single pieces on top. A piece keeps what each of its tiers was paid with (FPulseBuildPieceState_Payment): the factor (the knob times the factors of the cost adjustments, Construction::GetCostFactor) and, when an adjustment replaced the costs, that list (Construction::FindPaidCosts). Removing, undo and redo, the later stages of a site and a destroyed piece give back and take what that payment took, also after the difficulty or the adjustments changed. A repair is a new payment and follows the knob and the adjustments of now. Pieces of older saves and pieces game code adds without paying count factor 1 and the costs of the definition. The preview and the menus show the cost lines (FPulseCostLine from GetPlacementCostLines, GetUpgradeCostLines, GetRepairCostLines, GetRemoveRefundLines): label, icon, what the player has and what it costs. A cost that is only text shows a line without numbers; when a client cannot know what the player has, it shows only what it costs.

Who pays: the player who acts. Payment stages of a site are paid by the player who works on it, else the player who placed it, else a builder of the owner in this world. A stage is due when the work stands at its limit; a site whose next stage nobody can pay stalls until someone can.

The subsystem remembers the players of a site by id, with the build component only as a cache (FPulseBuildSitePlayer): the placer and the dismantler by player id (UPulseBuildComponent::GetPlayerId, the net id or player name, FallbackPlayerId without a player state), so a builder of the owner pays after loading or when the placer’s component is gone, also AI builders by FallbackPlayerId, and a player who comes back gets the dismantle refund (without an undo entry: an earlier session started the removal). Workers are matched by builder id (GetBuilderId, the runtime key of a build component), so builders that share a player id stay separate workers. Every build component registers with the subsystem (RegisterBuilder, FindBuilder, FindBuilderById); a player with two build components (pawn and player state) pays with the one FindBuildComponent finds.

Paying runs game code (a Blueprint Cost, the Items cost of PulseGameplay, bridges), which can change the building world. The subsystem therefore plans on a copy: it pays one stage at a time, and after each payment it checks that the piece still exists with the same definition, tier, size and site progress. If the site was removed, resized, finished or paid by someone else meanwhile, every stage paid in that call is given back (with the reversed rounding, so exactly what was paid) and AddWork returns PieceNotFound. Otherwise only the progress (work, paid stages, stall) is written onto the site as it is now: what game code changed while paying (place, workers, auto build) stays.

Every payment has a context (FPulseCostContext): the owner of the build component as Player, its pawn as Instigator, the piece definition as Source, the piece’s actor or cluster as Target, the place as Location, and FPulseBuildCostExtra (build component, piece definition, tier, piece id) as Extra. Fraction, Offset and bReverse carry the size, the payment stage and the rounding. A refund without a payer (a destroyed piece) has no Player; costs drop it at Location.

Construction sites

The Construction trait makes a new piece a site:

Property Meaning
BuildTime Seconds of work for tier 0 (0: placed finished)
bAutoBuild The site builds itself; off: players must work on it (Work tool, RequestStartWork, or holding the interaction with the PulseGameplay bridge)
DismantleTime Seconds until a removed piece is gone (the refund comes then; RequestCancelDismantle stops it)
SiteMesh Shown while tier 0 is built (scaffold); empty: the piece mesh, materials read the progress

Workers add WorkSpeed seconds of work per second each and stay on the site while in range. The knob Pulse.Tuning.Build.Duration divides all work (sites, upgrades, dismantling; the piece definition is the source of the context), so 2 makes every build take twice as long, also on sites that already run. The timer of the subsystem (ConstructionInterval) only runs while there are active sites. Progress is sent to clients in steps (ConstructionProgressStep) and at every payment stage. Pulse.Build.Instant 1 skips all build times.

Events: OnConstructionCompleted (and the message Pulse.Message.Build.Completed).

Tiers

The Tiers trait lists upgrades after tier 0 (BaseTierName, BaseTierTags). Each FPulseBuildTier has a display name, mesh, materials, max health, costs, build time and tags (Wood, Stone, Metal, … for rules, resistances and integrity). RequestUpgrade(Id) pays the costs and starts the upgrade (a site again when the tier has a build time). OnPieceUpgraded, message Pulse.Message.Build.Upgraded.

Health, damage and repair

The Health trait gives a piece MaxHealth (tiers can override it). Health is a state only while the piece is damaged. Damage comes from bridges or game code: ApplyDamage(Id, Amount, Instigator); damage of 0 or less does nothing. The knob Pulse.Tuning.Build.Damage scales it (the instigator is in the context); decay has its own. The new health is written first, then OnPieceDamaged and Damaged follow. At 0 the piece is destroyed (DestroyPiece): it is removed first (OnPieceRemoved, Removed), DestroyedRefundFraction of its value is refunded without a payer (the Items cost of PulseGameplay drops it as pickups where the piece stood), and only then come OnPieceDamaged (the killing blow, with the piece at 0 health; no Damaged message for it), the Destroyed message and OnPieceDestroyed (with the piece as it was stored). A listener of Destroyed no longer finds the piece. RequestRepair(Id) heals fully for RepairCostFraction of the value; Repair heals without costs. When game code heals the piece while the repair is paid, RequestRepair gives back the part that was not needed (everything when nothing was left to repair). Repair writes the health first and sends Repaired only after that. Events: OnPieceDamaged, OnPieceDestroyed; messages Damaged, Repaired, Destroyed.

Decay

The Decay trait takes DamagePerHour from a piece with health, scaled by the knob Pulse.Tuning.Build.Decay and the decay adjustments of the piece. With bOnlyWithoutUpkeep the piece only decays while UPulseBuildConstructionSubsystem::IsUpkeepPaid returns false (a Piece Decay adjustment with bIgnoreUpkeep lets it decay anyway); without a bound hook it always decays. Claims bind the hook when the game did not: pieces inside a claim of their owner do not decay (bClaimsPreventDecay). Decay steps run every DecayInterval seconds and count the hours since the last step: decay pauses with the game clock, follows its rate and catches up when it jumps (a rest of PulseTime). Construction steps (ConstructionInterval) count game-clock seconds the same way.

Which hours DamagePerHour counts is the setting HourUnit:

HourUnit One hour is With a calendar
DayHour (default) an hour of the day: 3600 game-clock seconds divided by the day rate PulseTime with a 24-minute day (day rate 60) makes pieces lose DamagePerHour every game-clock minute
GameClockHour 3600 game-clock seconds The speed of the day does not matter

Without a calendar the day rate is 1 and both are the same. When the day rate changes, the time since the last step decays with the old rate first, then the new rate counts. Day rate 0 (the hours of the day stand still) stops DayHour decay. SkipHours and SkipToHour of PulseTime move only the day, not the game clock, so no decay happens across them; a rest moves the game clock and decays. Projects that used PulseTime with PulseBuild before HourUnit existed decayed per game-clock hour: set HourUnit to GameClockHour to keep that speed.

Adjustments

Tuning sources (a difficulty level, an event, a reward, server rules; see tuning of PulseFoundation) carry adjustments next to their knob values. Pulse Build reads three types, each for one piece (its target):

Adjustment What it does
Piece Costs (FPulseAdjustment_BuildPieceCost) Tier (-1: every tier); Change Factor: the costs times Factor (0: free), or Replace: other Costs (the same Pulse costs as in the costs trait)
Lock Piece (FPulseAdjustment_BuildPieceLock) The piece cannot be built; Reason for the menu and the answer (empty: “This piece is locked.”)
Piece Decay (FPulseAdjustment_BuildDecay) DamagePerHour times Factor (0: no decay); bIgnoreUpkeep: decays also with paid upkeep

They apply in the order of the sources (priority, key, then the order in the source): factors multiply (also with Pulse.Tuning.Cost), the first Replace wins, any lock locks. Tags and Conditions of an adjustment are matched against the context of the piece (Adjustments::MakePieceContext): the piece definition as Source, its category, tags and tier tags in Tags (plus the cost kind for costs), the builder as Player. A personal source (a talent) counts for its player only.

  • Costs: what is paid now uses the adjusted costs: placing, upgrades, blueprints, the preview and the cost lines (GetPlacementCostLines, …). The piece keeps the factor and a replaced list (see Costs), so taking the adjustment away later neither makes nor destroys resources.
  • Lock: CanBuildPiece is false, SelectPiece and the server answer Pulse.Result.Failure.Build.Locked (EPulseBuildResult::Locked), also for an upgrade of a placed piece. Placed pieces stay; they can be moved, repaired and removed. GetAvailablePieces keeps locked pieces, so a menu can show them greyed out with IsPieceLocked(Piece, Reason). Free build (Pulse.Build.Free 1) ignores locks.
  • Decay: the decay step reads Adjustments::GetDecayPerHour; the knob counts on top.

Every machine computes the same from the replicated tuning. The build component listens to Pulse.Message.Tuning.Changed and calls NotifyAvailablePiecesChanged when adjustments or the difficulty change, so build menus update. The pure functions in Pulse::Build::Adjustments (GetEffectiveCosts, IsPieceLocked, GetDecayPerHour, MakePieceContext) take the tuning data as a parameter; the editor uses them for the values per difficulty level (Editor tools).

Rules without a world

The rules of sites and health are pure functions in Pulse::Build::Construction (no world, no settings, no console variables); specs and tools can call them on their own data:

Function What it does
GetDecayHours(GameSeconds, DayRate, Unit) Hours of decay in game-clock seconds: times the day rate over 3600 for DayHour, over 3600 for GameClockHour
GetSiteWork(Site, Seconds, WorkerSpeeds) Seconds of work for one step: the seconds when the site builds itself or is dismantled, plus seconds times speed per worker
AdvanceSite(Site, Seconds) Adds work up to the next unpaid stage, without paying (FPulseBuildSiteAdvance: the site, bStageDue, RemainingSeconds, bFinished)
MarkStagePaid(Site), SetStagePart(Context, Site) Marks the due stage paid; sets the part of the whole cost the next stage pays
ShouldSendSite(Before, After, Step) Whether clients get the change now (progress step, paid stage, stall)
IsSameSite(A, B), MergeSiteProgress(Current, Planned) Whether game code changed the progress while paying; writes only work, paid stages and stall
GetPayerCandidates(Participants, Owner, Builder) Who may pay the next stage, in order: the given builder alone, else workers, the placer, the owner by id
ApplyHealthDelta(Piece, Delta, OutPiece) Damage or healing (FPulseBuildHealthChange: before, after, max, changed, destroyed)

The subsystem is the shell around them: it plans the work with AdvanceSite, pays the due stage, checks that the site is unchanged, marks it paid and plans again with the seconds left; at the end it merges only the progress onto the site as it is now and writes it.

Value

What a piece is worth is its costs per tier (the list it was paid with) times the factor it was paid with, its size factor (spline length) and the paid part of a site. Removing refunds RefundFraction of the value of finished pieces and everything a site took. Undo and redo pay or refund value differences (see Blueprints, undo and hotbar).

Messages

Authority messages on the PulseFoundation message bus, payload FPulseBuildMessage (piece, instigator), registered with their payload (console Pulse.Messages.List): Pulse.Message.Build.Placed, .Removed, .Changed, .Completed, .Upgraded, .Damaged, .Repaired, .Destroyed (and .Collapsed of integrity). Destroyed comes after Removed; its target is the cluster that held the piece, as for Removed (none for actor pieces, whose actor is gone with the piece).

Their context (Pulse::Build::MakeMessageContext) lets the conditions of quests, achievements and message triggers filter them (“a stone wall placed by the player”):

Field Value
Instigator Who did it (the builder’s pawn, the attacker), may be empty
Player The instigator when it is a player’s pawn, controller or player state
Source The piece definition
Tags Category, tags and tier tags of the piece
Location The piece
Target The actor of an actor piece, else its cluster
Amount Damaged: the damage; Repaired: the restored health; Upgraded: the new tier; else 1

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