Gathering

Module PulseGathering (depends on PulseInventory, PulseAbility and PulseCombat). Trees, rocks and bushes the player harvests: by holding the interaction, by hitting them with a tool, or both. A harvest gives items from a loot table into the inventory, wears the tool, and the node shows how much is left until it grows back.

Overview

Type What it is
UPulseResourceNodeDefinition Data asset (Primary Asset Type PulseResourceNode): how a node is harvested, the tool it needs, its yield, its look per stage and its regrow time
APulseResourceNode The placed node: an actor with a mesh, an interactable and a hit box; replicated, dormant, no tick
FPulseItemTrait_GatheringTool Item trait Gathering Tool: tool tags (Pulse.Gathering.Tool.*) and a tier
FPulseCondition_CanHarvest Condition Can Harvest Node: harvests left and a fitting tool; the interactable of every node has it
UPulseGatheringSettings Project Settings > Pulse > Gameplay > Gathering

Setup

  1. The player needs an inventory (UPulseInventoryComponent) and, for tools, equipment (UPulseEquipmentComponent) on the pawn, the controller or the player state. Harvesting by interaction needs the interact ability; harvesting by hits needs a melee weapon (see Melee).
  2. Create a Resource Node in the Pulse window (Create) or with Add > Pulse > Gameplay > Resource Node.
  3. Give it a Yield (a loot table), a Full Mesh and the tools it needs.
  4. Place Pulse Resource Node actors in the level and set their Definition. Nodes can also be spawned on the server (SetDefinition before BeginPlay, or the cheat PulseGatheringSpawn).
  5. Make tools: items with the traits Equippable, Weapon (melee, for hits), Durability and Gathering Tool with a tag such as Pulse.Gathering.Tool.Axe.

Harvesting

How What happens
Holding the interaction bHarvestByInteraction: the prompt shows ActionText and DisplayName (“Chop Tree”), the player holds for HoldDuration seconds. Clients interact through the server (bReplicateInteractionEvents).
Hits bHarvestByHits: every HitsPerHarvest hits of a melee attack harvest once. Nodes take hits from every attacker, also from attacks that only hit enemies (IsHitByAnyAttacker of IPulseDamageable).

Each harvest, on the server:

  1. checks the node (harvests left) and the tool (CanHarvest),
  2. rolls the Yield table, scaled by the tool tier: 1 + (Tier - MinToolTier) * YieldBonusPerTier, rounded, at least 1 per drop,
  3. gives the items to the harvester’s inventory; what does not fit drops next to the node (bDropWhatDoesNotFit, DropScatterRadius),
  4. wears the tool by DurabilityLoss (negative: the tool’s LossPerUse, through FPulseItemTrait_Durability::Wear; a broken tool or no loss writes nothing) when it was harvested by interaction; a swung tool already wears per hit like every weapon (Combat with items),
  5. takes one harvest and sends Pulse.Message.Gathering.Harvested (see below) and OnHarvested.

Tools

RequiredTools lists the tool tags that can harvest a node (any of them); empty means by hand. MinToolTier is the lowest tier that works. The tool is found in the equipment of the harvester: the item in the active hotbar slot first, then the best fitting tool of the other active slots (slots outside the hotbar, such as the hands). Hotbar items that are not selected do not count.

Without a fitting tool the prompt shows the reason in place of the action, “Needs: Axe” (or “Needs: Axe (tier 2)”). ToolText names the tool; empty uses the last part of the first tool tag.

The plugin brings the roots Pulse.Gathering.Tool and Pulse.Gathering.Resource; add your own tags below them, e.g. Pulse.Gathering.Tool.Sickle or Pulse.Gathering.Resource.Fiber. ResourceTags of a definition travel with the harvest message, so quests and statistics can count wood or stone without knowing the node.

Stages and regrowing

Stage When Look
Full every harvest left FullMesh, Material
Partial after the first harvest PartialMesh (empty: the full mesh), PartialScale, Material
Exhausted nothing left ExhaustedMesh (empty: hidden), ExhaustedScale, ExhaustedMaterial; no interaction, no hits

bStandOnGround keeps the bottom of the mesh on the actor location in every stage, so a short stump stays on the ground. The stage is derived from the harvests left, so clients only receive that number.

Every RegrowTime seconds an exhausted or partial node gets one harvest back (0 never regrows). The node keeps the moment the next harvest grows back as a stamp on the Pulse game clock (FPulseResourceNodeState::RegrowAt), so regrowing follows the game rate and stops while the game clock is paused; a late wake-up catches up (one harvest per RegrowTime that passed). Worlds without the clock (editor previews) count world time. A node in Pulse Sim (below) regrows as an event of its record; other nodes get one timer of the game clock as a wake-up on the server (UPulseClockSubsystem::SetTimer), which follows pause, rate and jumps of the clock. Nothing ticks.

Pulse Sim

With Keep In Pulse Sim (on by default, category Sim) the state of a node lives in a Pulse Sim record of Pulse Foundation (kind FPulseSimState_ResourceNode: the state, the harvests of a full node and the regrow time). The node shows the record:

  • The record regrows the node, also while its level or chunk is unloaded; a node that comes back shows what grew in the meantime and the rest of the wait.
  • Pulse Sim saves the records with the world (its save actor and PulseSave’s byte collector): no save model is needed.
  • Every change of the node (harvest, hit, SetRemainingHarvests, SetNodeState, LoadFromBytes) is written into the record; a change of the record made by other code is shown by the node. A load of Pulse Sim that replaces the record keeps the node bound.
  • The record id is the save key of a placed node (<level>.<actor>.Pulse.Gathering.Save.Node, GetSimRecordId). Spawned nodes change their names in every session: give them a Sim Record Id, otherwise they keep their state on the actor as before. Without Pulse Sim running (bEnabled of its settings) every node keeps its own timer.
  • The record has the notice Pulse.Gathering.Sim.Regrew (amount = harvests left) on Pulse.Message.Sim.Event when a harvest grows back.

Saving the state

GetNodeState / SetNodeState (same session) and SaveToBytes / LoadFromBytes (versioned FPulseResourceNodeSaveData with the seconds left, across sessions) keep the wait: a node saved 20 of 60 seconds before its next harvest regrows 20 seconds after loading. SetRemainingHarvests sets the harvests left directly (cheats, simple saves) and starts a fresh wait when none runs. Nodes of the endless world (PulseWorldGameplayBridge) are spawned without a Sim Record Id and store only the harvests left, so they regrow only while their chunk is loaded.

Tuning

Three tuning knobs of PulseFoundation change every node, by its resource tags (the tags of the context; the definition is the source):

  • Pulse.Tuning.Gathering.Yield multiplies the items of a harvest after the bonus of the tool (rounded, at least 1 per stack). The loot table itself also follows Pulse.Tuning.Inventory.LootAmount (see Loot).
  • Pulse.Tuning.Gathering.Regrow multiplies the seconds a harvest needs to grow back; a wait that runs keeps its end.
  • Pulse.Tuning.Gathering.ToolTier (a bonus from -3 to 3) is added to Min Tool Tier of every node (rounded, at least 1): a hard level needs better tools. The bonus per tier above the minimum counts from the new minimum.

Resource Node adjustment

A tuning source (a difficulty level, a zone, an event) can change nodes with the adjustment Resource Node (FPulseAdjustment_ResourceNode, in PulseGatheringValues.h). With a Node it changes that definition; without one it is a rule for every node whose resource tags match its Tags.

Field Meaning
Harvests Bonus Added to the harvests of a full node (at least 1)
Min Tool Tier Bonus Added to the minimal tool tier (at least 1)
Yield Factor Multiplies the yield, together with the knob Yield
Regrow Factor Multiplies the seconds per harvest, together with the knob Regrow

A level can also use another node instead with Swap Asset (a variant of the definition): the node resolves its definition once at BeginPlay, on every machine.

The node reads all numbers from one function, Pulse::Gathering::GetNodeValues(Definition, TuningData, Context) (FPulseResourceNodeValues: Harvests, MinToolTier, YieldBonusPerTier, YieldFactor, RegrowTime), and keeps the result (GetNodeValues on the node). It builds it again on every tuning change, on every machine; a smaller node clamps the harvests left at once, a wait that runs keeps its end, the Pulse Sim record gets the new harvests and regrow time. Personal sources do not change the node for everyone: only the yield of a harvest adds the personal sources of the harvester.

In the editor

Resource node definitions open in the config workshop of the Pulse Editor Kit with the preview Node:

  • Viewport: the full, partial and exhausted stage side by side (mesh, scale, material, Stand On Ground), buttons to show one stage, and a fourth mesh with the stage after Seconds since exhausted. The camera frames the shown meshes when the preview opens (again with Focus, F, or the View option Reframe When the Content Changes). A node without a Full Mesh shows the engine cube in its full and partial stage and says so in the info line; an exhausted stage without a mesh stays hidden, as in the game.
  • Level buttons (Pulse Difficulty; Base is the asset as it is) and a line when the level swaps the node.
  • Values: harvests, min tool tier, regrow time and yield factor on the chosen level, with the value of every level in one line.
  • Yield per tool tier: the hand and every tier up to three above the minimum, with the factor and the items (“Wood 2-3 (avg 2.6)”), from the exact chances of the yield table (Pulse::Inventory::Loot::ComputeChances with the loot adjustments of the level). Tiers that cannot harvest are grey with the reason.
  • Adjustments of the level with their before and after, and Where used (levels, presets, spawners).

Regrow Time and Min Tool Tier are registered as tuned properties (their knob shows per level in tables), the Resource Node adjustment has a before and after preview, the Gathering Tool trait shows “Axe tier 2” on its card, and a loot table lists the nodes whose yield it is under Where used. The pure rules: Pulse::Gameplay::Editor::Gathering::MakeTierRows, and for the viewport MakePreviewMeshes, GetPreviewMesh and GetPreviewBounds; specs PulseGathering.Values and PulseGameplay.Editor.GatheringWorkshop.

A tool that wears per harvest loses durability through Pulse.Tuning.Inventory.Wear (see Durability).

Multiplayer

  • Harvests run on the server. The definition is sent once (COND_InitialOnly), afterwards only the harvests left: the state is one property, NodeState, of which only RemainingHarvests replicates (hits and the regrow stamp stay on the server).
  • Nodes placed in the level are dormant until something changes (DORM_Initial); spawned nodes go dormant after their first replication. Every change of the harvests left (harvest, regrow, SetRemainingHarvests, SetNodeState) wakes the node for one update.
  • NodeNetCullDistance (default 200 m) limits how far away clients get nodes.

Collision

The mesh is WorldStatic (profile BlockAll) like other world objects: the interaction query, traces and navigation find it. Melee attacks look for Pawn and PhysicsBody objects, so the node has a second component, HitShape: a query-only box around the mesh of the stage that blocks nothing and is off while the node is exhausted.

Message

Pulse.Message.Gathering.Harvested (payload FPulseHarvestMessage: node, definition, harvester, items, source, harvests left). The context carries the harvester as player and instigator, the node as target, the definition as source, the resource tags as tags and the number of items as amount.

Blueprint and C++

Function What it does
Harvest(Harvester, Source) Harvests once for a harvester (authority).
CanHarvest(Harvester, OutReason) Whether a harvester can harvest now, and why not (any machine).
SetRemainingHarvests(Remaining) Sets the harvests left (authority); starts a fresh wait when none runs.
GetNodeState, SetNodeState(State) The whole state (harvests left, hits, regrow stamp); set it on the authority.
GetRegrowSecondsLeft Game seconds until the next harvest grows back (authority).
SaveToBytes, LoadFromBytes Versioned save bytes that keep the wait (C++, authority).
GetRemainingHarvests, GetMaxHarvests, GetStage, GetDefinition State of the node.
GetSimRecordId, IsBoundToSim The id of the Pulse Sim record, and whether the node shows it (authority).
OnHarvested / OnHarvestedNative After a harvest, on the authority.
OnStageChanged On every machine when the stage changed.
Pulse::Gathering::FindTool The tool a harvester would use for a node (C++).

GetNodeValues on the node gives the numbers it uses now (definition with knobs and adjustments). In PulseGatheringValues.h: MakeNodeContext, GetNodeValues, GetYieldPerTier, GetStageAfterRegrow, GetHarvestsAfterRegrow (pure, spec PulseGathering.Values).

The rules are pure functions in PulseGatheringTypes.h (CheckTool, GetYieldMultiplier, ScaleDrops, GetStage, WearTool, Regrow; for the node state GetRemaining, RegisterHit, TakeHarvest, Advance, WithRemaining, ToSaveData, FromSaveData); the specs PulseGathering.Rules, PulseGathering.Node and PulseGathering.Sim (the kind and the binding) test them.

Example

The example map LV_PulseGameplay_Example has three trees (left of the start) and two rocks (right of it), built from /PulseGameplay/Examples/Gathering: DA_PulseExample_Tree (axe, hold 1.5 s or 3 hits, 3 harvests, regrows every 30 s) and DA_PulseExample_Rock (pickaxe, hold 2 s or 4 hits, regrows every 45 s), with the items wood, stone, axe and pickaxe. PulseGatheringGrant (part of PulseGameplayGrant) puts the axe on hotbar slot 4 and the pickaxe on slot 5.

Cheats

See Console.


PulseGameplay plugin documentation.

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