Player Resource Send Threshold

[keithharvey]

Player Resource Send Threshold

Introduces a new configurable threshold for resource sharing tax, for both energy and metal.

• creates a per-team policy cache using SetTeamRulesParam
• this lets the UI ask for bounds for metal/energy transfers to teammates
• this result is used to drive the UI in gui_advplayerslist directly
• deprecates the AllowResourceTransfer hook in prevent_excessive_share. game_tax_resource_sharing is now the only handler and it just transfers within bounds defined by the policy, if that is possible.

Note: This is a complete rewrite of the tax system mostly to accommodate the new requirements without exploding gui_advplayerslist, but a side effect of this is that it simplifies the UI considerably.

Demo Video

How does it work?

Right away and then every N frames: game_tax_resource_sharing.lua will build and cache a tax policy for each team pair <-> resource type (energy and metal). It uses a single function for both resource type calculations and follows that pattern of functional reuse between synced and unsynced to ensure all resource transfer follows the same rules and is driven by the same contract: the policy result.

---@class ResourcePolicyResult : PolicyResult
---@field canShare boolean
---@field amountSendable number
---@field amountReceivable number
---@field taxedPortion number
---@field untaxedPortion number
---@field taxRate number
---@field resourceType ResourceType
---@field remainingTaxFreeAllowance number
---@field resourceShareThreshold number
---@field cumulativeSent number

This policy result is then serialized and thrown into a cache:

local hypothetical_resource_policy_result = "remainingTaxFreeAllowance:400:resourceShareThreshold:400:canShare:1:untaxedPortion:400:taxedPortion:0:taxRate:0.5:resourceType:energy:cumulativeSent:0:amountSendable:400:amountReceivable:0"
local baseKey = string.format("policy_cache_%d_%s_", receiverId, resourceType)
Spring.SetTeamRulesParam(senderId, baseKey, serialized)

This gives you a serialized policy result that the UI can quickly grab if it needs to know the bounds of a particular transfer. This also gives you a shared type to use across synced and unsynced functions.

Testing Results

• Verified threshold logic:
  • Metal/Energy sent below the sender’s cumulative threshold is tax-free.
  • Metal/Energy sent after the sender exceeds their cumulative threshold is taxed correctly based on tax_resource_sharing_amount.
• Confirmed UI preview and slider cap behavior:
  • Metal/Energy upper bound stable and intuitive.
  • Label fits for two-number display and remains adjacent to the slider.
  • Echo message includes threshold context only when configured.

LLM usage disclosure

None. I tried LLM for this, it was hard. Ended up validating it with unit tests and then backporting this raw implementation by hand.

[keithharvey]

Rebased

[WilliamPas]

Rejected by the GDT: This is counter to our desired game design, we want to address co-op issues via balance rather than arbitrary restrictions.

[PtaQQ]

Reopened after the new decision by the GDT. Awaiting code review.

[keithharvey]

Rebased

[drivver44]

blocked until @thehobojoe does a review

[thehobojoe]

This PR is fine, but it needs a way to communicate to the player what is happening with their metal, and when taxes are going to kick in and how much it will cost them.

This could be as simple as an echo to the team, but I would prefer some indication during sharing that communicates the threshold and the taxes before they send resources.

[keithharvey]

Great suggestions. Updated the description with the requested changes. Was able to get this one completely right. Squashed it.

[keithharvey]

Closed this because I am consolidating further into #5704 which presents a complete UX and functional solution.