Tuning knobs

A tuning knob is a number or switch of a plugin that a difficulty, the server rules, an area, an event or a cheat may change: the damage players take, the time a recipe needs, the costs of building, what happens to the inventory on death. The plugin registers its knobs and reads them where it uses the number; whoever wants to change them sets a source with values. No plugin needs a bridge to a difficulty plugin, and a project sees every knob of its plugins in one list. Where a number is not enough (a recipe with other ingredients, a loot table swapped for another), a source carries adjustments as well.

Pulse Foundation never sets a source by itself, except the server rules when a server starts and the area function Adjustments while its area exists.

Knobs

A knob is a gameplay tag under Pulse.Tuning with an entry in the register (FPulseTuningKnob):

Field What it is
Tag The knob (Pulse.Tuning.Crafting.Duration).
DisplayName, Description, Category For menus that list the knobs (a custom difficulty) and for the docs.
Kind Factor (values of all sources multiply), Bonus (they add up), Switch (on or off) or Choice (one of Choices): switches and choices follow the source with the highest priority.
Min, Max Bounds of a factor or bonus: no source may set a value outside, and the combined value stays inside.
bDefaultOn, DefaultChoice A switch or choice without any source (DefaultChoice empty: the first option).
bPerPlayer Whether a source may set it for one player only (the damage that player takes, their hunger): a personal source.
Plugin Who registered it.

Register knobs in StartupModule of the module that reads them, remove them in ShutdownModule:

FPulseTuningKnob knob;
knob.Tag = TAG_Pulse_Tuning_Crafting_Duration;
knob.DisplayName = LOCTEXT("CraftingDuration", "Crafting time");
knob.Description = LOCTEXT("CraftingDurationText", "Factor of the time every recipe needs.");
knob.Category = LOCTEXT("CategoryCrafting", "Crafting");
knob.Kind = EPulseTuningKind::Factor;
knob.Min = 0.1f;
knob.Max = 10.f;
knob.Plugin = TEXT("MyPlugin");
Pulse::Tuning::RegisterKnob(knob);

Read it where the number is used, with the context of what it is about (player, tags, source):

const double seconds = Pulse::Tuning::Apply(this, TAG_Pulse_Tuning_Crafting_Duration, Recipe->Duration, Context);
const int32 count = Pulse::Tuning::ApplyCount(this, TAG_Pulse_Tuning_Crafting_Ingredients, Ingredient.Count, Context, EPulseTuningRounding::Up, 1);
const bool bPermadeath = Pulse::Tuning::IsOn(this, TAG_Pulse_Tuning_Save_Permadeath, Context);

Apply multiplies by the factor or adds the bonus, ApplyCount rounds (up, down or to the nearest) and keeps a minimum for counts above 0, IsOn and GetChoice read switches and choices. Without tuning in the world (an editor world) the knob has its defaults. The pure functions take the data instead of a world (Pulse::Tuning::Evaluate(Knob, Data, Context), ApplyValue, ApplyCountValue), so plugins test their rules without one.

Blueprint: Apply Tuning, Apply Tuning Count, Is Tuning On, Get Tuning Choice, Evaluate Tuning (the value with the sources it comes from), Get Tuning Knobs, Find Tuning Knob.

Sources

A source (FPulseTuningSource) is a set of values under a key:

Field What it is
Key Unique per player: “Difficulty”, “ServerRules”, “Area.Volcano”. Setting a source with the same key replaces it as a whole.
Label Name in the debugger and in menus.
Priority Higher first: decides switches and choices; factors and bonuses of all sources count.
PlayerId Only for this player (Pulse::Player::GetPlayerId): a personal source. Empty: for everyone.
Values The values (FPulseTuningValue): the knob, Value (factor or bonus), bOn (switch), Choice, and where it applies.
Adjustments Adjustments of the plugins (FPulseAdjustment).
Presets Presets (UPulseTuningPreset) whose values and adjustments count as part of the source, after its own: only the reference goes over the network.

A value applies where the tags of the context match its Tags query and its Conditions pass: only costs of the kind building, only enemies, only this recipe, only players in an area. A condition that cannot decide on a client counts as not passed there. Sources with the same priority are ordered by key, so the result never depends on the order they were set in.

On the server, UPulseTuningSubsystem sets them (Blueprint Set Tuning Source, Remove Tuning Source):

FPulseTuningSource source;
source.Key = TEXT("Difficulty");
source.Label = LOCTEXT("Hard", "Hard");
source.Values.Add(FPulseTuningValue::MakeNumber(TAG_Pulse_Tuning_Combat_DamageTaken, 1.5f));
source.Values.Add(FPulseTuningValue::MakeChoice(TAG_Pulse_Tuning_Death_Inventory, TEXT("Drop")));
const FPulseResult result = UPulseTuningSubsystem::Get(this)->SetSource(source);

SetSource checks the source first (Pulse::Tuning::ValidateSource): a key, values inside the bounds, options the knob has, personal values only for knobs with bPerPlayer. A failure answers Pulse.Result.Failure.Invalid with the text why and changes nothing. Values of knobs nobody registered pass (their plugin may be off) and are left out.

Costs and rewards

Two knobs of Pulse Foundation scale the costs and rewards of every plugin at one place:

  • Pulse.Tuning.Cost: Pulse::Costs::GetAmount multiplies every cost by it (items, building points, skill points), rounded over the whole like the payment stages (Costs). Plugins put the kind of the cost into the tags of the payment context (Pulse.CostKind.Build), so a value can change one kind only. Pulse Skill Perk Draft pays its reroll costs with the kind Pulse.CostKind.PerkReroll. Pulse Combat Shooter pays the ammunition of a reload with the kind Pulse.CostKind.Ammo. The cost lists read the factor once per payment (Pulse::Costs::ResolveTuning); FPulseCostContext::TuningFactor keeps it. Systems that give back later (building, skill refunds) store the factor of the payment and set it for the refund, so a changed difficulty neither makes nor destroys resources.
  • Pulse.Tuning.Reward: Pulse::Rewards::GetAmount(Amount, Context, Kind) multiplies the amount of a reward (items, experience, currency) and rounds it to the nearest whole number; the kind (Pulse.RewardKind.Experience) goes into the tags the values filter by. Rewards of your own call it for what they give. The reward Influence of Pulse Faction Territory gives its influence with the kind Pulse.RewardKind.Influence.

The attribute entries of Pulse Foundation (Attributes) use both knobs without rounding: the cost Attribute pays Amount x factor x Fraction with the kind Pulse.CostKind.Attribute, the reward Change Attribute tunes Add and Set amounts with the kind Pulse.RewardKind.Attribute (parts of the range and Reset stay as they are). A cost list reads its factor once for the whole payment, before its entries see it: to tune attribute costs alone inside a list, put Pulse.CostKind.Attribute into the tags of the payment context; a single cost without a factor adds the kind itself.

Adjustments

An adjustment (FPulseAdjustment, Tuning/PulseAdjustment.h) is a change to data whose form a plugin defines: a recipe with three iron bars instead of two, ores 20 % heavier, a loot table swapped for another. Plugins derive their own types from it (instanced structs with meta = (BaseStruct = "/Script/PulseFoundation.PulseAdjustment")), collect them where they read the data and apply them themselves, so every machine computes the same. Every adjustment has Tags and Conditions like a value, and answers three questions:

Function What it answers
GetTarget() The asset it changes; empty for a rule that picks its targets itself (“all weapons: one more leather”).
GetDisplayText() The line for menus and the debugger.
Validate() Whether it is complete (target set, values that fit); checked before a source with it is set and in Pulse Check.

Pulse Foundation brings three, Pulse Gameplay brings more:

Type What it does
Set Tuning Knob (FPulseAdjustment_Tuning) A knob value, for lists that hold only adjustments.
Swap Asset (FPulseAdjustment_Swap) Uses Replacement instead of Original: a recipe, a loot table, a quest, an AI profile. The plugin asks Pulse::Adjustments::Resolve before it uses the asset. Chains count (A to B, B to C), circles end where they started. Make the replacement a variant of the original in the workshop, so it keeps what is not changed.
Reward Give Adjustments (FPulseReward_Adjustments) Sets values, adjustments and presets as a source with a fixed key, for the player who gets it (a talent, equipment) or for everyone (a world event). Revoke removes exactly that source; Reapply sets it again after loading.
Change Recipe, Change Recipes by Rule, Lock Recipes (PulseGameplay, FPulseAdjustment_Recipe, _RecipeRule, _RecipeLock) Ingredients, counts, duration and station tags of one recipe or of the recipes a filter selects; locked recipes cannot be crafted (crafting).
Item Modifier (PulseGameplay, FPulseAdjustment_ItemModifier) Weight, durability, stack size, spoil rate, value or a number of a trait of the items a filter selects, for the inventories of the player of the context; no conditions, so clients and the server compute the same (trait modifiers).
Loot Weight (PulseGameplay, FPulseAdjustment_LootWeight) Factor of the weight of loot entries whose item has a tag, in every loot table (a difficulty with fewer rare weapons); 0 removes them from the weighted rolls.
Piece Costs, Lock Piece, Piece Decay (PulseBuild, FPulseAdjustment_BuildPieceCost, _BuildPieceLock, _BuildDecay) Factor or other cost lists of a piece (all tiers or one), a piece that cannot be built (placed pieces stay), the decay of a piece; paid factors and replaced lists are kept with the piece for refunds and repairs (construction, locked pieces).
World Options (PulseWorld, FPulseAdjustment_WorldOptions) Steps of world options a difficulty suggests in the menu New World (fewer resources on a hard level); the player’s choice and share codes win, never read in a running world (world types).
Boat Hull (PulseWater, FPulseAdjustment_BoatHull) Hull health, armor, leak size and bilge pump rate of one boat type or of every boat; swaps of boat definitions go through Swap Asset (boats).
Change Crop (PulseFarming, FPulseAdjustment_Crop) Grow hours, water per day, yield and harvests of one crop or of the crops whose tags match; a Swap Asset of a crop is resolved when sowing (crops).
Resource Node (PulseGameplay, FPulseAdjustment_ResourceNode) Harvests, minimal tool tier, yield and regrow time of one resource node or of the nodes whose resource tags match (gathering).
Merchant Price (PulseGameplay, FPulseAdjustment_MerchantPrice) Buy and sell factor of the items with a tag, at one merchant or at every merchant; a Swap Asset of a merchant picks a variant (merchants).

A plugin reads them where it uses the data:

// The recipe as this context sees it
const UPulseRecipe* recipe = Pulse::Adjustments::ResolveObject(this, BaseRecipe, Context);
for (const FMyAdjustment_Recipe* change : Pulse::Adjustments::Collect<FMyAdjustment_Recipe>(this, FSoftObjectPath(recipe), Context))
	change->ApplyTo(EffectiveRecipe);

Collect<T>(WorldContext, Target, Context) returns the adjustments of a type (and its children) for a target, with the rules without a target, in the order of the sources: priority, key, then the order in the source (its own adjustments, then those of its presets). Personal sources count for their player only. The pointers stay valid until the tuning changes: read them right away, or cache the result with the generation (Get Tuning Generation). The pure versions take FPulseTuningData instead of a world. Pulse.Message.Tuning.Changed says when adjustments changed (bAdjustmentsChanged) and which targets (Targets).

Presets (UPulseTuningPreset, a data asset with values and adjustments) are the way to share a set between sources and to keep the network light: a difficulty level, a game mode, an event. Presets check their values and adjustments in the data validation of the editor.

Difficulty level

The tuning also holds the difficulty level of the game (FPulseDifficultyLevel): a tag under Pulse.Difficulty and a rank (higher is harder), plus the lowest level played since the game started. SetDifficulty (Blueprint Set Difficulty) changes it on the server, ResetLowestDifficulty starts the lowest level again for a new game. The level itself changes no knob: the source of the difficulty does.

The tuning is not saved. An owner that keeps the history itself (a difficulty system with its save data) sets the lowest level after a load with SetLowestDifficulty (Blueprint Set Lowest Difficulty, pure Pulse::Tuning::PutLowestDifficulty): it replaces the value instead of keeping the minimum, a level above the current one is taken as the current one, an empty level clears it. Call it after SetDifficulty.

Two conditions read it in every Pulse list (loot, quests, dialogs, achievements):

Condition Passes when
Difficulty the current level (or with Lowest Played the lowest level played) is one of Levels and, with bCompareRank, its rank compares to Rank (“never played below Hard”)
Tuning Knob a switch is on or off, a choice is an option, or a factor or bonus compares to a number, for the context

Server rules

When a server or standalone world starts, the server rules become the source ServerRules (priority ServerRulesPriority, 1000): the section [PulseTuning] of Game.ini and -PulseTuning= on the command line, a later rule for the same knob wins (the command line after the config). Names without Pulse.Tuning. are fine:

[PulseTuning]
Cost=0.5
Crafting.Duration=2
Save.Permadeath=On
MyGameServer.exe -PulseTuning="Cost=0.5;Combat.DamageTaken=1.5"

Factors and bonuses take numbers, switches On/Off (1/0, True/False), choices the name of an option. Rules that do not fit (unknown knob, a value outside the bounds) are left out with a warning in the log. bApplyServerRules turns it off.

Multiplayer

The server holds the sources and sends them with APulseTuningState: the sources for everyone and the difficulty to every client, personal sources only to the machine of their player. Every machine evaluates the knobs from what it has, so a client shows the same costs the server takes (with personal sources of other players left out, which the client never needs). On a listen server the host evaluates with every source.

Every change is sent on the message bus on every machine: Pulse.Message.Tuning.Changed (payload FPulseTuningChangedMessage: source, player, removed, the knobs it touches, difficulty, generation; the knobs are also the tags of the context). What a client receives when it joins comes as catch-up (Replication). Widgets that show tuned values refresh when Get Tuning Generation changes.

Saving

Sources are not saved: whoever sets a source sets it again after loading (a difficulty from its asset or its saved choice, a reward through Reapply, an area when it starts). That way a source always has the values of its current assets. The same holds for the difficulty level.

Debugging

Tool What it shows
Pulse.Tuning.List Every registered knob with kind, bounds, per player, plugin and, in a game, the value without a context and the sources it comes from
Pulse.Tuning.Set Cost=0.5 Crafting.Duration=2 Sets knobs as the source Cheat on the server (without rules: removes it), for the console of a dedicated server
Cheats PulseTuningInfo, PulseTuningSet, PulseTuningMine, PulseDifficulty See Console
Pulse Debugger Snapshot Tuning (difficulty, sources and their values) and the timeline source Foundation, category Tuning, for every change

UPulseTuningDraft (Tuning/PulseTuningDraft.h) holds the values of a source while a player edits them: Load a source, change it with SetNumber (clamped to the bounds of the knob), SetSwitch, SetChoice (only options of the knob) and ResetValue, switch adjustments with SetAdjustment. Nothing counts until Apply: it sets the source through the tuning subsystem (server) or calls OnApply, which a menu of a client sets to send its request.

UPulseTuningMenuWidget (PulseFoundationUI, Tuning/PulseTuningMenu.h) shows an entry per registered knob (grouped by category; a personal draft only lists knobs with bPerPlayer; Plugins limits it). The default entries are built in code in the UI theme: a slider with the number for factors and bonuses (“×1.5”, “+5”), a check box for switches, the option with “<” and “>” for choices. Replace them per kind or per knob with Pulse::UI::Tuning::RegisterEntryClass (a Blueprint child of UPulseTuningEntryWidget implements On Entry Set and writes the draft).

In the editor

The editor kit (Kit/Tuning/PulseTuningEditor.h) shows what tuning does without playing:

  • Before and after: MakeAdjustmentPreview compares the target of an adjustment with the result (DiffValues of two captures of the workshop values); a swap compares the original with the replacement, other types register RegisterAdjustmentPreview (apply the adjustment to a transient copy). MakeBeforeAfterPanel draws the changed values, the original faint and the result bright, with a reset button per value.
  • Effect: FindAffected lists the assets an adjustment hits: its target and what RegisterAffectedFinder of its type finds (a rule for many recipes); MakeEffectPanel with a button that opens each.
  • Where used: FindUsages gives the referencers of an asset in the asset registry and what the finders of its class add (RegisterUsageFinder: a recipe that names an item by id). The start page of every config workshop shows them under Used by.
  • Value per level: a plugin that knows the difficulty levels (PulseDifficulty) registers them with RegisterLevelProvider; EvaluatePerLevel and FormatPerLevel evaluate a knob on each level without a world (“Easy 5 · Hard 15”). Number properties registered with RegisterTunedProperty (class, property, knob) show their value per level next to the cell in Pulse Tables.

Knobs of the Pulse plugins

Knob Kind Per player Plugin What it changes
Pulse.Tuning.Cost Factor 0 to 10 no PulseFoundation Every cost paid through the cost lists; filter by Pulse.CostKind.*
Pulse.Tuning.Reward Factor 0 to 10 no PulseFoundation Every reward amount of rewards that use Pulse::Rewards::GetAmount; filter by Pulse.RewardKind.*
Pulse.Tuning.AI.Perception Factor 0.1 to 10 no PulseAI Sight and hearing ranges of agents, on top of the profile; their roles (Pulse.AI.Role.*) are in the tags
Pulse.Tuning.AI.ReactionTime Factor 0.1 to 10 no PulseAI Time agents need to notice what they see (lower is harder)
Pulse.Tuning.AI.Aggression Factor 0.1 to 10 no PulseAI Aggression of agents (the result stays between 0 and 1)
Pulse.Tuning.AI.Speed Factor 0.1 to 10 no PulseAI Walk and run speeds of agents
Pulse.Tuning.Achievements.Enabled Switch, on no PulseAchievement Off: no achievement unlocks (also not online); counters keep counting
Pulse.Tuning.Attributes.RateGain Factor 0 to 10 yes PulseFoundation Rising rates of attributes (stamina and health coming back); the old Pulse.Tuning.Attributes.Regeneration is redirected here
Pulse.Tuning.Attributes.RateLoss Factor 0 to 10 yes PulseFoundation Falling rates of attributes (hunger, thirst, oxygen, and health while starving); the old Pulse.Tuning.Attributes.BarDecay is redirected here
Pulse.Tuning.Build.Duration Factor 0.1 to 10 no PulseBuild Work of construction sites, upgrades and dismantling
Pulse.Tuning.Build.Decay Factor 0 to 10 no PulseBuild Damage decay does to pieces
Pulse.Tuning.Build.Damage Factor 0 to 10 no PulseBuild Damage pieces take (not decay); the attacker is the instigator
Pulse.Tuning.Combat.DamageTaken Factor 0 to 10 yes PulseGameplay Damage players take; the damage type and its tags are the tags
Pulse.Tuning.Combat.DamageDealt Factor 0 to 10 no PulseGameplay Damage players deal
Pulse.Tuning.Combat.EnemyHealth Factor 0.1 to 10 no PulseGameplay Max health of combatants that are no players, at once, keeping the share
Pulse.Tuning.CombatAction.ParryWindow Factor 0 to 10 yes PulseCombatAction Length of the parry window
Pulse.Tuning.CombatAction.DodgeIFrames Factor 0 to 10 yes PulseCombatAction Length of the invulnerability frames of a dodge
Pulse.Tuning.CombatAction.PoiseDamage Factor 0 to 10 yes PulseCombatAction Poise damage a combatant takes
Pulse.Tuning.CombatAction.PoiseRegen Factor 0 to 10 yes PulseCombatAction Poise regained per second
Pulse.Tuning.CombatAction.CounterWindow Factor 0 to 10 yes PulseCombatAction Length of the counter window
Pulse.Tuning.CombatAction.StaggerTime Factor 0 to 10 no PulseCombatAction Length of every stagger
Pulse.Tuning.CombatAction.CounterDamage Factor 0 to 10 no PulseCombatAction Damage factor of counter hits (above 1 only the bonus part)
Pulse.Tuning.CombatElements.BuildUp Factor 0 to 10 no PulseCombatElements Build-up hits add to an element on a target
Pulse.Tuning.CombatElements.TickDamage Factor 0 to 10 no PulseCombatElements Damage of the ticks of an element
Pulse.Tuning.CombatElements.Duration Factor 0 to 10 no PulseCombatElements Seconds an element lasts on a target
Pulse.Tuning.CombatShooter.Spread Factor 0 to 10 no PulseCombatShooter Spread of shooter weapons (never coupled to recoil)
Pulse.Tuning.CombatShooter.Recoil Factor 0 to 10 no PulseCombatShooter Recoil of shooter weapons on the local view
Pulse.Tuning.CombatShooter.ReloadTime Factor 0 to 10 no PulseCombatShooter Seconds of a reload
Pulse.Tuning.Crafting.Ingredients Factor 0 to 10 no PulseGameplay Ingredient counts (rounded up, at least 1, tools stay); the recipe category and station tags are the tags
Pulse.Tuning.Crafting.Outputs Factor 0 to 10 no PulseGameplay Output counts (rounded, at least 1)
Pulse.Tuning.Crafting.Duration Factor 0.1 to 10 no PulseGameplay Seconds of a round, read when a job starts
Pulse.Tuning.Death.Inventory Choice Settings, Keep, Drop, Destroy yes PulseGameplay What happens to the inventory of a player who dies
Pulse.Tuning.Faction.ReputationGain Factor 0 to 10 no PulseFaction Reputation gains; the faction tag is in the tags
Pulse.Tuning.Faction.ReputationLoss Factor 0 to 10 no PulseFaction Reputation losses
Pulse.Tuning.FactionTerritory.Gain Factor 0 to 10 no PulseFactionTerritory Influence players inside a territory give; the territory tag is in the tags
Pulse.Tuning.FactionTerritory.Decay Factor 0 to 10 no PulseFactionTerritory How fast influence in a territory falls; the territory tag is in the tags
Pulse.Tuning.Farming.GrowthTime Factor 0.1 to 10 no PulseFarming Hours of every stage of a plant, read when it is sown and kept in the plant; the crop tags are the tags
Pulse.Tuning.Farming.WaterUse Factor 0 to 10 no PulseFarming Water a plant uses per day, read when it is sown and kept in the plant
Pulse.Tuning.Farming.Yield Factor 0 to 10 no PulseFarming Items of a harvest (rounded, at least 1 per stack); the harvester is the player, the crop tags the tags
Pulse.Tuning.Gathering.Yield Factor 0 to 10 no PulseGameplay Items of a harvest after the tool bonus; the resource tags are the tags
Pulse.Tuning.Gathering.Regrow Factor 0.1 to 10 no PulseGameplay Seconds a harvest needs to grow back
Pulse.Tuning.Gathering.ToolTier Bonus -3 to 3 no PulseGameplay Tiers added to the minimal tool tier of a resource node (rounded, at least 1); the resource tags are the tags
Pulse.Tuning.Inventory.LootAmount Factor 0 to 10 no PulseGameplay Counts a loot table gives (rounded, at least 1)
Pulse.Tuning.Inventory.Wear Factor 0 to 10 no PulseGameplay Durability an item loses per use; the item tags are the tags
Pulse.Tuning.Inventory.Spoilage Factor 0 to 10 yes PulseGameplay Spoil rate of new perishable stacks
Pulse.Tuning.Inventory.CarryWeight Factor 0 to 10 yes PulseGameplay Weight limit of inventories; below the load they are overloaded (take nothing more)
Pulse.Tuning.Inventory.BuyPrice Factor 0 to 10 no PulseGameplay Prices players pay to merchants
Pulse.Tuning.Inventory.SellPrice Factor 0 to 10 no PulseGameplay Prices merchants pay to players
Pulse.Tuning.Inventory.UseCooldown Factor 0 to 10 no PulseGameplay Cooldown after an item was used; the item tags and its cooldown group are the tags
Pulse.Tuning.Quest.TimeLimit Factor 0.1 to 10 no PulseQuest Time limits of timer objectives, at once; the quest tag is in the tags
Pulse.Tuning.Respawn.BleedOut Factor 0 to 10 yes PulseGameplay Seconds until a downed player bleeds out (downed mode)
Pulse.Tuning.Respawn.Delay Factor 0 to 10 yes PulseGameplay Seconds until a dead player may respawn and until the automatic respawn
Pulse.Tuning.Respawn.Permadeath Switch, off no PulseGameplay Deaths are permanent: no respawn, a downed player can still be revived; without a source the Permadeath switch of the respawn settings decides
Pulse.Tuning.Save.Ironman Switch, off no PulseSave One save per game that only auto saves write; the game loads only from the main menu, never while it runs
Pulse.Tuning.Water.HullDamage Factor 0 to 10 no PulseWater Damage boat hulls take, before the armor

PulseFoundation plugin documentation.

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