references/economies-and-probability.md
# Economies and Probability
Use this reference for resource-flow models, affordability and stability checks, random outcome tables, expected value, variance, and streak analysis.
## Economy Boundary
First decide whose economy is being modeled:
- One player during an encounter.
- One player across progression.
- A cohort over calendar time.
- A shared market with transfers between players.
- The entire game, including resources created or destroyed by system actors.
A transfer is a sink for one actor and a source for another, but it is neither at the whole-economy boundary unless a fee destroys part of it.
## Resource Ledger
Create one row per resource or currency.
| Field | Prompt |
| --- | --- |
| Resource | What is counted, exchanged, or constrained? |
| Purpose | Which decisions does it enable? |
| Sources | How much enters, how often, and for whom? |
| Sinks | How much leaves, how often, and for whom? |
| Transfers | Which actors exchange it without creating or destroying it? |
| Conversions | Which resources become which others, at what rate and loss? |
| Stock | Where is it stored? |
| Bounds | Capacity, debt floor, decay, or expiration |
| Visibility | Exact, estimated, or hidden from players |
| Time scale | Action, session, day, season, or lifetime |
## Stock and Flow Equations
For one actor over one interval:
```text
stock_next = stock_now
+ created
+ transfers_in
- destroyed
- transfers_out
```
For a currency with purchases and fees:
```text
stock_next = stock_now + earned + granted + purchased
- prices_paid - fees - decay
```
At the whole-economy boundary, player-to-player prices paid cancel with receipts. Transaction fees do not.
Useful rates:
```text
net_flow_per_hour = source_per_hour - sink_per_hour
source_sink_ratio = source_per_hour / max(sink_per_hour, epsilon)
currency_velocity = amount_spent_during_period / average_stock_during_period
```
Define affordability piecewise:
```text
time_to_afford = 0 when current_stock >= price
time_to_afford = (price - current_stock) / net_flow when net_flow > 0
time_to_afford = unreachable otherwise
```
Interpret ratios in context. A progression economy may intentionally have positive net flow; a mature shared economy may need stronger recurring sinks.
## Economy Scenario Sheet
| Scenario | Starting stock | Source events | Sink events | Ending stock | Key purchase affordable? | Decisions remaining? |
| --- | ---: | ---: | ---: | ---: | --- | --- |
| first session | | | | | | |
| typical returning player | | | | | | |
| expert optimizer | | | | | | |
| low-engagement player | | | | | | |
| hoarder | | | | | | |
| spender | | | | | | |
| maximum progression | | | | | | |
Run the ledger by cohort and percentile. Average stock can look healthy while new players are starved and veterans hold unusable fortunes.
## Price and Reward Checks
For every important purchase or reward, calculate:
- Earliest, median, and late time-to-afford.
- Opportunity cost in units of the next-best purchase.
- Purchase frequency and repeatability.
- Value after progression, not only at introduction.
- Whether saving is always superior to spending now.
- Whether the item creates new decisions or only larger output.
- Whether the price is a meaningful sink at the cohort that can buy it.
For a conversion chain, multiply yields and losses:
```text
final_output = initial_input * yield_1 * yield_2 * ... * yield_n
```
Track time, capacity, and byproducts separately. A profitable ratio can still stagnate if conversion is too slow or storage is too small.
## Worked Economy Example: Beacon Marks
A route game grants `12` marks after an ordinary expedition. Expected repairs cost `3` marks per expedition. A route-chart upgrade costs `45` marks.
```text
net_marks_per_expedition = 12 - 3 = 9
expeditions_to_upgrade = 45 / 9 = 5
```
If the target is an upgrade every 4 to 6 ordinary expeditions, the mean fits. That is not enough verification:
- A damaged expedition may cost `11` to repair, creating only `1` net mark.
- A flawless expedition may avoid repairs and grant a `6` mark bonus.
- Players may also spend `8` marks on a temporary forecast.
- A second upgrade at `90` marks changes cumulative pacing.
Model at least the 10th, 50th, and 90th percentile time-to-upgrade and the share of expeditions where the forecast is a credible alternative. If players never buy forecasts, raising their reward may be less appropriate than changing forecast timing, information value, or duration.
## Economy Diagnostics
### Inflation
Signals:
- Holdings grow faster than useful prices or sinks.
- Currency velocity falls while balances rise.
- Formerly meaningful rewards become negligible.
- Players substitute another scarce item as an informal store of value.
Checks:
- Source and sink rates by cohort and version.
- Holdings at median, 90th, and 99th percentiles.
- Share of stock owned by top holders.
- Repeatable versus one-time sinks.
- Resource creation from exploits, automation, or duplicate grants.
### Stagnation
Signals:
- Players delay every purchase.
- Transactions fall despite unmet goals.
- Mandatory maintenance consumes most income.
- One failure removes the means to recover.
Checks:
- Net flow after mandatory costs.
- Time-to-afford by low and median performance.
- Expected value of spending now versus saving.
- Minimum viable action budget.
- Availability of costly but credible recovery routes.
### Hoarding
Hoarding can indicate uncertainty, missing future information, weak sinks, excessive loss aversion, or inventory friction. Do not assume the stock cap alone is the solution. Test whether players understand future needs and whether current spending produces visible value.
## Probability Event Worksheet
```text
Event name:
Player decision affected:
Possible outcomes and values:
Weights or probabilities:
Independent, conditional, or stateful:
Replacement/reset rule:
Frequency:
Impact of one outcome:
Player-visible odds:
Expected value:
Variance/standard deviation:
Failure or drought percentiles:
Guarantee, pity, or cap state:
Rounding and random-seed behavior:
```
## Core Probability Formulas
For equally likely outcomes:
```text
P(success) = successful_outcomes / total_outcomes
```
For weighted outcomes:
```text
P(outcome_i) = weight_i / sum(all_weights)
```
Expected value:
```text
E[X] = sum(P(outcome_i) * value_i)
```
Variance and standard deviation:
```text
Var(X) = sum(P(outcome_i) * value_i^2) - E[X]^2
SD(X) = sqrt(Var(X))
```
For independent events:
```text
P(A and B) = P(A) * P(B)
P(A or B) = P(A) + P(B) - P(A and B)
```
For a conditional event:
```text
P(A and B) = P(A) * P(B given A)
```
For at least one success in `n` independent trials with constant chance `p`:
```text
P(at_least_one) = 1 - (1 - p)^n
P(no_successes) = (1 - p)^n
```
Expected attempts to first success for independent constant chance:
```text
E[attempts] = 1 / p
```
Expected attempts is not a guarantee or a typical maximum. Always inspect percentiles.
Trials needed to reach probability `q` of at least one success:
```text
n = ceil(ln(1 - q) / ln(1 - p))
```
This form requires `0 < p < 1` and `0 < q < 1`.
For exactly `k` successes in `n` independent trials:
```text
P(K = k) = combination(n, k) * p^k * (1 - p)^(n - k)
```
## Without Replacement
When outcomes are removed from a pool, probabilities change after every draw.
If a pool begins with `S` successes among `T` items, the chance of two successes without replacement is:
```text
P(two successes) = (S / T) * ((S - 1) / (T - 1))
```
Do not use independent-roll formulas for decks, bags, rotating shops, or loot pools unless the item is replaced and the pool resets exactly as assumed.
## Stateful Guarantees
A guarantee, escalating chance, duplicate protection, or cooldown makes each roll conditional on prior state.
Model it as a transition table:
| State before roll | Success chance | On failure | On success |
| --- | ---: | --- | --- |
| 0 prior failures | | state 1 | reset or new state |
| 1 prior failure | | state 2 | reset or new state |
| ... | | | |
Calculate or simulate the complete distribution. Do not advertise the base chance as if it described the whole stateful process. Preserve any required disclosures and avoid misleading player-facing odds.
## Worked Probability Example: Salvage Cache
| Outcome | Weight | Probability | Value |
| --- | ---: | ---: | ---: |
| Scrap | 60 | 0.60 | 2 |
| Battery | 25 | 0.25 | 6 |
| Lens | 10 | 0.10 | 15 |
| Core | 5 | 0.05 | 40 |
Expected value:
```text
E[X] = 0.60*2 + 0.25*6 + 0.10*15 + 0.05*40 = 6.2
```
Second moment and spread:
```text
E[X^2] = 0.60*2^2 + 0.25*6^2 + 0.10*15^2 + 0.05*40^2 = 113.9
Var(X) = 113.9 - 6.2^2 = 75.46
SD(X) ~= 8.69
```
The standard deviation exceeds the mean, so short sequences feel volatile.
Chance of at least one Core in 20 independent caches:
```text
1 - (1 - 0.05)^20 ~= 0.642
```
About 35.8% of players would still see no Core after 20 caches under the independent model. If that drought is unacceptable, change the distribution or add a stateful guarantee, then recalculate the economy impact and full wait-time distribution.
## Randomness Diagnostics
- **Mean is correct, experience is harsh:** inspect variance, lower percentiles, droughts, and impact per event.
- **Players distrust displayed odds:** audit implementation, rounding, dependency, event selection, and whether the displayed chance is conditional.
- **Rare reward floods economy:** multiply probability by event frequency, active population, and reward value.
- **Randomness overwhelms skill:** reduce impact per event, give players decisions after the roll, or distribute randomness across more lower-impact events.
- **Outcome feels scripted:** check streak prevention, small sample size, visible patterns, and repeated seed behavior.
- **Guarantee is exploitable:** inspect reset conditions, shared counters, mode switching, and partial progress persistence.
- **Choice is fake under uncertainty:** compare expected value and downside for each option using the information actually available to the player.
## Verification
- Economy boundary and time unit are explicit.
- Transfers are not mistaken for creation or destruction at the aggregate level.
- Every stock reconciles from one interval to the next.
- Affordability is checked by cohort and percentile.
- Weighted probabilities normalize to 1 within tolerance.
- Analytical results match enumeration for a small test case.
- Independent and dependent events are distinguished correctly.
- Expected value, variance, and relevant tail probabilities are reported together.
- Stateful guarantees are modeled with their reset and transition rules.
- Random reward changes are propagated through source rates and economy forecasts.
- Player-visible odds and implementation behavior agree.
references/quantitative-modeling.md
# Quantitative Modeling
Use this reference to create measurable targets, maintainable spreadsheets, comparable attributes, stable fulcrums, and intentional progression curves.
## Balance Brief
```text
Design decision:
Player segment:
Context and available choices:
Time horizon:
Primary experience target:
Primary metric and target interval:
Guardrail metrics and intervals:
Known asymmetries that should remain:
Current baseline and evidence quality:
Model assumptions:
Decision threshold:
Owner and review date:
```
Prefer intervals over exact points unless the rule requires exact conservation. A target of 45-60 seconds to resolve an ordinary encounter is more honest and useful than 52.3 seconds when player behavior drives variation.
## Attribute Dictionary
| Field | Purpose |
| --- | --- |
| Attribute name | Stable, unambiguous identifier |
| Design meaning | What concept it abstracts |
| Mechanics usage | Which rules consume it |
| Unit | Seconds, meters, points, percentage, items, and so on |
| Valid range | Technical and design bounds |
| Default/fulcrum | Ordinary reference value |
| Kind | input, derived, context, outcome, or display |
| Visibility | hidden, approximate, or exact to players |
| Persistence | action, encounter, session, or account |
| Formula/source | Authoritative origin |
| Owner | Who may change it |
Remove an attribute when no rule, decision, display, or analysis uses it. Combine attributes whose differences never produce different player choices.
## Workbook Layout
Use a structure that another designer can audit without oral explanation:
```text
00_ReadMe purpose, owners, units, conventions, versions, change log
01_Parameters named constants, range endpoints, weights, caps
02_Entities one row per comparable object, input attributes only
03_Curves progression tables and marginal changes
04_Derived intermediate and final formulas
05_Scenarios controlled contexts and assumptions
06_Checks invariants, bounds, missing values, duplicate IDs
07_Results summaries, quantiles, charts, comparisons
08_RawRuns imported simulation, playtest, or telemetry extracts
99_Scratch disposable calculations that are not authoritative
```
### Conventions
- Use named parameters or stable references instead of repeated literals.
- Label every table, unit, formula output, and data version.
- Keep one row per object and one column per attribute inside data tables.
- Do not use blank rows as category markers; add a category column.
- Validate types, enumerations, and ranges at input.
- Protect formula cells and make tunable cells visually distinct with a documented convention.
- Break long formulas into named intermediate columns.
- Separate raw source data from cleaned data and calculated output.
- Add invariant checks whose correct result is already known.
- Keep full internal precision; round only in dedicated display columns or at a specified implementation boundary.
## Useful Checks
```text
IDs are unique
required cells are nonblank
minimum <= value <= maximum
probabilities sum to 1 within tolerance
source total - sink total = stock change
normalized values remain in [0, 1]
curve is monotonic where intended
display rounding does not change tier/order unexpectedly
lookup keys all resolve
simulation and model versions match
```
Use a small numeric tolerance for floating-point checks rather than exact equality where appropriate.
## Normalized Ranges
Map a native unit into a common design range:
```text
n = clamp((x - min_x) / (max_x - min_x), 0, 1)
x = min_x + n * (max_x - min_x)
```
If `max_x = min_x`, the range is undefined. Fix the model rather than dividing by zero.
Normalization helps compare unlike scales, but it does not make unlike attributes equally valuable. Weight or combine them only after measuring how they affect outcomes.
### Range Worksheet
```text
Attribute:
Native unit:
Technical minimum/maximum:
Playable minimum/maximum:
Ordinary operating band:
Player-visible scale:
Reason for endpoints:
Behavior below/above endpoints:
Rounding/display rule:
Evidence used to revise range:
```
Reserve room beyond ordinary values when temporary effects, future content, or injuries need it. Test whether players can perceive the smallest meaningful step.
## Reference Fulcrum
A fulcrum is an ordinary, stable comparison object or scenario. It need not ship. It should represent the middle of intended play, not the arithmetic middle of every raw range.
### Fulcrum Worksheet
```text
Object family:
Ordinary use context:
Outcome targets:
Input attributes:
Scenario assumptions:
Known strengths intentionally absent:
Known weaknesses intentionally absent:
Tests required before freezing:
Version and evidence:
Conditions that permit revision:
```
Workflow:
1. Start with middle-of-range inputs.
2. Test the fulcrum against itself or against the ordinary scenario.
3. Adjust one input at a time until outcome targets and feel are credible.
4. Test across representative contexts.
5. Freeze a version and derive variants from it.
6. Compare each variant to the fulcrum with the same scenarios.
7. Cross-test extremes, counters, synergies, and unique mechanics.
Do not permanently freeze a broken reference. Reopening it should be rare, explicit, versioned, and followed by regression of every derived family.
## Weighted Screening Score
Normalize first, then weight:
```text
screening_score = sum(weight_i * normalized_attribute_i)
```
Document whether higher is always better. Invert costs or drawbacks when needed:
```text
normalized_benefit_of_low_cost = 1 - normalized_cost
```
Use the score to identify likely outliers and seed tests. Do not use it as final proof because interactions, thresholds, timing, and context violate simple additivity.
## Intertwined Attributes
Derive a gameplay outcome before assigning value.
### Throughput
```text
actions_per_second = 1 / cycle_seconds
throughput = amount_per_action * actions_per_second * success_probability * uptime
```
Include reload, recovery, travel, resource starvation, or animation lock in `cycle_seconds` or `uptime` when they matter.
### Time to Resolution
For deterministic discrete hits:
```text
hits_required = ceil(target_health / damage_per_hit)
time_to_defeat = windup + (hits_required - 1) * cycle_seconds
```
The final hit has no following cooldown, so multiplying every hit by the full cycle can overstate time.
For expected continuous output:
```text
estimated_time_to_defeat = target_health / effective_damage_per_second
```
Use simulation when misses, critical hits, reloads, overkill, control effects, or target behavior make the distribution important.
### Effective Durability
For damage reduction `r` in `[0, 1)`:
```text
effective_durability = health / (1 - r)
```
This estimate fails when reduction is type-specific, capped per hit, bypassed, or changed during the encounter. Model those scenarios separately.
### Progression Time
```text
steps_to_goal = required_resource / expected_resource_per_step
time_to_goal = required_resource / expected_resource_per_minute
cumulative_time(rank) = sum(time_to_complete_each_prior_rank)
```
Graph per-rank time and cumulative time. A gentle-looking cost curve can produce an exhausting cumulative curve.
## Curve Recipes
Let `x` start at zero unless stated otherwise.
### Linear
```text
y(x) = start + step * x
```
Use when each step should add the same absolute amount. Solve a line through endpoints:
```text
step = (end - start) / number_of_steps
```
### Exponential
```text
y(x) = start * ratio^x
ratio = (end / start)^(1 / number_of_steps)
```
Use when each step should add the same percentage. `start` and `end` must be positive for this form.
### Power
```text
y(x) = start + scale * x^p
```
- `p > 1`: accelerating absolute gains.
- `0 < p < 1`: diminishing absolute gains.
### Saturating Return
```text
y(x) = cap * x / (half_point + x)
```
At `x = half_point`, output reaches half of `cap`. Use for resistance, reputation benefit, accuracy support, or any value that should approach but not reach a ceiling.
### Logarithmic Return
```text
y(x) = start + scale * ln(1 + x)
```
Use for strong early benefit with a long, slowly improving tail. Keep `x >= 0`.
### Piecewise
```text
y(x) = early_rule(x) when x < breakpoint
y(x) = late_rule(x) when x >= breakpoint
```
Use when the design intentionally changes phase. Check continuity at the breakpoint unless a visible jump is desired.
## Curve Review Worksheet
```text
Design purpose:
Input and output units:
Domain:
Required start/middle/end values:
Desired marginal change:
Chosen family and why:
Cap/floor:
Breakpoints:
Display rounding:
Time-to-earn assumptions:
First five outputs:
Middle outputs:
Last five outputs:
One step beyond domain:
Largest absolute step:
Largest percentage step:
```
Plot:
- Total output `y(x)`.
- Absolute marginal change `y(x) - y(x-1)`.
- Proportional change `y(x) / y(x-1) - 1`.
- Player time or actions required to obtain each step.
## Worked Example: Salvage Tools
Three tools in a salvage game should produce similar long-run material throughput in their favored ordinary context while supporting different risk preferences.
```text
throughput_per_minute = payload * success_probability / cycle_seconds * 60
```
| Tool | Payload | Success | Cycle seconds | Expected per minute |
| --- | ---: | ---: | ---: | ---: |
| Clamp | 5 | 0.90 | 15.0 | 18.0 |
| Needle | 3 | 0.75 | 7.5 | 18.0 |
| Hauler | 9 | 0.60 | 18.0 | 18.0 |
`Clamp` is the fulcrum. Equal means do not make the tools interchangeable:
- Needle gets more attempts and recovers quickly from a miss, but requires more actions.
- Hauler has larger bursts and longer droughts, making interruption more costly.
- Clamp offers a steadier middle case.
Required follow-up models:
- Energy consumed per successful material.
- Lost payload when interrupted mid-cycle.
- Storage overfill and overkill waste.
- Player success rates rather than assumed success rates.
- Short encounter percentiles, where the means may not converge.
- Upgrade interactions that alter cycle, success, or payload together.
This example demonstrates the role of a fulcrum and an outcome metric. It does not prove balance until the contextual guardrails and player experience are tested.
## Verification
- All formulas use compatible units.
- Range mappings return 0, 0.5, and 1 at minimum, midpoint, and maximum.
- Inputs and derived values are not mixed in editable columns.
- Weighted scores use documented normalized direction and weights.
- The fulcrum is versioned and tied to scenario outcomes.
- Curves hit required endpoints and have intentional marginal behavior.
- Rounding is applied only at the stated boundary.
- Every chart includes labels, units, and the relevant domain.
- Model results are compared with at least one independent calculation or controlled test.
references/simulation-telemetry-and-tuning.md
# Simulation, Telemetry, and Tuning
Use simulation to explore repeated interacting rules, telemetry to observe real behavior at scale, and controlled tuning to connect evidence to reversible changes.
## Select the Evidence Method
| Method | Best for | Cannot establish alone |
| --- | --- | --- |
| Formula/enumeration | exact simple relationships and invariants | player strategy or perception |
| Deterministic trace | event order, boundaries, and edge cases | distribution across randomness |
| Stochastic simulation | distributions, repeated interactions, sensitivity | whether humans understand or enjoy it |
| Bot/agent tournament | policy matchups and exploit search | real player optimality |
| Moderated playtest | comprehension, decision process, and experience | population prevalence |
| Telemetry | behavior and outcomes at scale | causality or private intent by itself |
| Controlled live experiment | comparative causal evidence under stated assumptions | long-term effects outside its window |
Triangulate when the decision is costly or risky.
## Simulation Specification
```text
Decision to inform:
Model version:
Population/unit simulated:
Initial state distribution:
Time step and horizon:
Transition rules:
Random variables and distributions:
Agent policies and skill/noise assumptions:
Configurations compared:
Seeds and run count:
Stop conditions:
Metrics and quantiles:
Invariants:
Analytical cases used for verification:
Known omissions:
Decision threshold:
```
If agent behavior drives the result, treat policy assumptions as first-class inputs. Compare several policies rather than labeling one "the player."
## Engine-Agnostic Simulation Skeleton
```text
for each configuration:
for each seed:
random = seeded_generator(seed)
state = initialize(configuration, random)
while not finished(state):
observations = expose_information(state)
actions = choose_actions(observations, policies, random)
events = resolve_actions(state, actions, random)
state = apply_events(state, events)
assert_invariants(state)
record_step(configuration, seed, state, actions, events)
record_run_summary(configuration, seed, state)
aggregate_distributions()
compare_configurations()
```
Keep transition logic separate from policy logic. This lets the same game rules run under random, greedy, scripted, adversarial, and noisy skill-tier policies.
## Policy Set
Useful baseline policies include:
- Random legal choice: catches gross dominance and dead actions.
- Greedy immediate reward: exposes short-horizon exploits.
- Greedy long-term value: tests investment and snowball behavior.
- Rule-of-thumb novice: uses visible signals with execution noise.
- Experienced heuristic: uses known synergies and context.
- Adversarial search: seeks stalls, loops, denial, and degenerate states.
- Scripted edge policy: forces rare transitions and boundary states.
Document information available to each policy. A policy must not read hidden state unavailable to the intended player.
## Reproducibility and Verification
- Seed every random stream and store the seed per run.
- Store model, parameter, and policy versions with results.
- Verify a no-randomness case against a hand calculation.
- Verify a small random case by complete enumeration when feasible.
- Assert conservation, bounds, and legal-transition invariants every step.
- Run the same seed before and after a change for paired debugging.
- Confirm results do not depend accidentally on iteration order.
- Inspect raw traces for selected best, median, worst, and anomalous runs.
## Run Count and Uncertainty
Choose runs based on stability of the decision metric, not a ritual number.
For an approximately independent sample mean:
```text
standard_error = sample_standard_deviation / sqrt(n)
approx_95_percent_interval = mean +/- 1.96 * standard_error
```
For an observed proportion `p_hat`:
```text
standard_error ~= sqrt(p_hat * (1 - p_hat) / n)
```
Use a more appropriate interval for small samples or extreme proportions. Report at least count, mean or rate, median, and relevant low/high quantiles. Heavy-tailed results often need many more runs than stable central outcomes.
Convergence procedure:
1. Run a small batch.
2. Double the cumulative run count.
3. Compare key estimates and quantiles with the prior batch.
4. Continue until the decision remains unchanged within a stated tolerance or budget.
5. Report unresolved uncertainty rather than hiding it.
## Sensitivity Analysis
Use sensitivity to find leverage and brittle conclusions.
### One-Factor Sweep
Vary one input across and slightly beyond its legal range while holding others fixed. Plot outcomes and marginal change. Good for monotonicity, thresholds, and caps.
### Grid Sweep
Vary two high-impact inputs together. Use a heat map to reveal interactions and regions where the preferred option changes.
### Scenario Sweep
Run all candidate options across named contexts: close/far, rich/poor, solo/team, novice/expert, early/late progression, and low/high latency where relevant.
### Random Parameter Sampling
Sample several uncertain parameters from plausible ranges. Use this to see whether a conclusion survives uncertainty, not to replace thoughtful scenario design.
Rank inputs by how much they move the decision metric, but inspect interactions before declaring one lever causal.
## Simulation Output Template
```text
Question:
Compared configurations:
Policies and assumptions:
Runs/seeds:
Primary result with uncertainty:
Median and tail results:
Invariant failures:
Sensitivity reversals:
Representative traces:
Mismatch with analytical expectations:
Known model gaps:
Decision supported:
Next human test:
```
## Telemetry Question Map
Never begin with "track everything." Begin with a decision.
| Decision | Metric | Denominator/context | Event | Required properties | Threshold/action |
| --- | --- | --- | --- | --- | --- |
Example:
```text
Decision: revise the Hauler tool if it is understood but nonviable
Metric: selection rate and successful material per minute
Denominator: sessions where Hauler was unlocked, shown, and affordable
Context: route type, player progression, prior uses, and build version
Events: option_presented, option_selected, salvage_cycle_resolved
Action: revise if use remains low and contextual outcome is below guardrail
```
## Event Envelope
Use consistent shared fields:
```text
event_name
event_schema_version
timestamp
build_version
balance_data_version
anonymous_player_id
session_id
mode/map/encounter
progression_band
skill_or_match_band, if valid
experiment_id and variant, if any
```
Decision events should usually include:
```text
decision_id
options_available
eligibility and affordability
choice
relevant_state_before
relevant_state_after
outcome
```
Economy events should include resource, amount, stock before/after, source/sink category, transaction context, and counterparty type. Do not record unnecessary personal or sensitive information. Establish consent, access, retention, and deletion practices appropriate to the project and jurisdiction.
## Metric Definitions
### Conditional Choice Share
```text
choice_share(option) = selections(option) / valid_presentations(option)
```
Do not divide by all sessions when the option was locked, hidden, unaffordable, or incompatible in many sessions.
### Contextual Outcome
```text
outcome_rate = successful_outcomes / valid_attempts
```
Stratify by relevant context and skill. Comparing raw win rate between an expert-only unlock and a starter option creates selection bias.
### Economy Flow
```text
net_flow = sum(source_amounts) - sum(sink_amounts)
```
Report per player-hour or another meaningful exposure unit, plus holdings and spending quantiles.
### Progression and Friction
- Time and attempts to milestone by cohort.
- Failure and abandonment at each opportunity.
- Repeated failure before success.
- Help, skip, or difficulty-change use.
- Resource shortfall when a milestone is presented.
Define starts, completions, timeouts, and idle-time handling precisely.
## Telemetry Validation
Before trusting live results:
1. Generate every event in a controlled test.
2. Verify required properties and units.
3. Reconcile event counts with an independent local counter.
4. Test retries, duplication, offline queues, reconnects, and clock issues.
5. Confirm build and balance versions propagate correctly.
6. Check that option-presentation denominators exist.
7. Run impossible-value and missing-property monitors.
8. Compare a small set of session replays or logs with reconstructed metrics.
Instrumentation bugs can look exactly like balance changes.
## Analysis Guardrails
- Show sample size and missing-data rate.
- Use medians and quantiles alongside averages.
- Segment before drawing a global conclusion.
- Distinguish correlation, prediction, and causal comparison.
- Account for exposure and survivorship; late-game data represents players who reached late game.
- Mark balance patches, content launches, promotions, and population changes.
- Predefine primary metrics for controlled experiments.
- Avoid repeated peeking and many uncorrected comparisons.
- Check practical effect size, not only statistical significance.
- Pair telemetry with qualitative evidence when interpretation or fairness matters.
## Tuning Proposal
```text
Observed symptom:
Affected segment/context:
Evidence and limitations:
Diagnosed causal mechanism:
Current parameter(s):
Proposed parameter(s):
Why this is the lowest-impact lever:
Expected primary movement:
Guardrails expected not to move:
Model/check results:
Fixed-seed simulation results:
Playtest/live experiment plan:
Exposure and observation window:
Keep/revise/rollback thresholds:
Dependencies and regression risks:
Owner:
```
## Tuning Log
| Version/date | Hypothesis | Change | Primary result | Guardrails | Decision | Evidence link |
| --- | --- | --- | --- | --- | --- | --- |
Retain old values. A rollback should be a data/version change, not an attempt to reconstruct forgotten numbers.
## Causal Tuning Sequence
When an option appears too strong or weak, investigate in this order:
1. Was it actually available and understood?
2. Which contexts and players selected it?
3. Is the measured outcome the intended value it provides?
4. Does selection itself correlate with skill, progression, or team composition?
5. Which rule creates the advantage: base output, uptime, information, safety, denial, synergy, or economy access?
6. Can a contextual counter or clearer cost preserve identity better than a flat numeric change?
7. What downstream curves, economies, tutorials, AI, content, and achievements depend on the lever?
## Failure Modes
- **Simulation matches itself:** transition and verification use the same faulty formula. Add an independent hand or enumerated check.
- **One policy declared optimal:** policy assumptions determine the winner. Compare policies and information constraints.
- **More runs hide model error:** confidence narrows around a biased model. Validate structure before scale.
- **Only means reported:** droughts, blowouts, and long tails disappear. Report distributions and representative traces.
- **Telemetry lacks opportunity:** popularity denominator is wrong. Instrument presentation, eligibility, and affordability.
- **Version mixing:** incompatible balance states are aggregated. Require build and balance-data versions.
- **Metric becomes target:** tuning improves a proxy while harming the experience. Keep player-facing guardrails and qualitative checks.
- **Global fix for local cohort:** other modes or stages regress. Segment and choose a lower-level lever.
- **Uncontrolled live change:** population or content shifts confound the result. Use a comparison strategy and record concurrent changes.
- **No rollback condition:** a harmful patch persists through debate. Predefine thresholds and preserve prior data.
## Verification
- Simulation question, model, policy, horizon, and omissions are explicit.
- Seeds and versions reproduce selected traces.
- Simple cases agree with independent calculations.
- Invariants run during every simulation step.
- Run count is justified by convergence or decision tolerance.
- Results include distributions, uncertainty, and sensitivity reversals.
- Telemetry begins from a decision and records its denominator.
- Events include schema, build, and balance-data versions.
- Instrumentation is reconciled against controlled sessions.
- Analysis handles cohorts, exposure, outliers, and missing data.
- Tuning changes identify a causal lever, expected movement, guardrails, and rollback.
- The final decision updates the source of truth and tuning log.
SKILL.md
---
name: game-balance
description: "Numerically balances engine-agnostic weapons, units, encounters, progression, loot, difficulty, and economies using measurable targets, spreadsheets, curves, probability, simulation, telemetry, and playtests. Use for tuning values and distributions; defer mechanic ideation to game-mechanics-design and cross-system structure to game-systems-design."
license: MIT
metadata:
author: godot-skills
version: "1.0.0"
---
# Game Balance
Balance means fitting numbers and rules to an intended experience for defined players, contexts, and time horizons. It does not mean making every option equal.
Remain engine-agnostic. Put tunable inputs, formulas, assumptions, scenarios, and checks in inspectable artifacts. Write implementation guidance only after the model and evidence are clear.
## Core Principles
- Begin with a measurable design target, not a preferred number.
- State the population, skill band, context, and horizon for every balance claim.
- Preserve meaningful differences. Options can have equal expected value and still differ in risk, timing, information, execution burden, or situational fit.
- Treat player choice as evidence only when the choice was available, understood, and credible.
- Keep raw inputs, derived metrics, player-facing display values, and observed outcomes separate.
- Centralize shared parameters. Do not type the same balancing constant into many formulas.
- Use a reference fulcrum to compare a large family of objects, then cross-test the unusual interactions.
- Choose curve shape from the desired marginal change, not from habit.
- Analyze an economy as flows and stocks across time, not as a price list.
- Analyze random outcomes by distribution and tail risk, not expected value alone.
- Use deterministic checks first, simulation for interacting or stochastic behavior, playtests for experience, and telemetry for behavior at scale.
- Change one causal lever or coherent lever bundle at a time and retain a rollback path.
## Intake
Inspect existing rules, spreadsheets, data exports, code/configuration, test results, simulations, and telemetry definitions before changing values. Establish:
- Balance question and observed symptom.
- Intended player experience and definition of success.
- Player segments, skill levels, modes, maps, encounters, and progression stage.
- Relevant time horizon: action, encounter, session, day, season, or lifetime.
- Candidate choices and when each is available.
- Attributes, formulas, dependencies, units, ranges, rounding, and caps.
- Current source of truth and data pipeline.
- Available evidence and its sample/context limitations.
- Production, fairness, accessibility, business, and legal constraints.
If information is missing, label assumptions and design the smallest measurement or experiment that can replace them.
## Workflow
### 1. Write a Balance Contract
Use a testable statement:
```text
For [player segment] in [context] over [horizon],
[primary metric] should remain within [target range],
while [guardrail metrics] remain within [ranges].
We will change [decision] if [evidence threshold] is crossed.
```
Examples of valid target dimensions include time to resolution, success rate by skill band, choice diversity by context, recovery opportunity, progression time, resource surplus, reward drought, and perceived clarity.
Do not set equal pick rate or 50% win rate by default. Explain why a target fits the game's purpose.
### 2. Define the Comparison Context
List the conditions under which values are comparable:
- Player skill and knowledge.
- Opponent or challenge profile.
- Map, range, team size, and mode.
- Starting resources and persistent power.
- Input method, latency, and execution assumptions.
- Duration and stop condition.
A global average across incompatible contexts is not a balance result. Segment first, aggregate second.
### 3. Build the Attribute Model
For each object and attribute, define meaning, unit, valid range, source, visibility, mutability, and mechanics that consume it. Mark attributes as:
- Input: directly tuned.
- Derived: calculated from inputs.
- Context: supplied by a scenario.
- Outcome: measured from play or simulation.
- Display: rounded or transformed for players.
Use [Quantitative Modeling](references/quantitative-modeling.md) for the balance brief, workbook layout, attribute worksheet, normalization, fulcrums, formulas, curves, and original worked example.
### 4. Structure the Spreadsheet or Model
At minimum, separate:
1. Read-me, assumptions, units, and change history.
2. Parameters and named constants.
3. Entity inputs.
4. Curves and lookup tables.
5. Derived calculations.
6. Representative scenarios.
7. Invariants and error checks.
8. Results, distributions, and charts.
9. Raw simulation or playtest imports.
Use one row per comparable object and one column per attribute. Validate input types and bounds. Keep intermediate calculations visible while debugging; hide or group them only after verification.
### 5. Establish Ranges and a Fulcrum
Normalize unlike units for comparison:
```text
normalized = clamp((value - minimum) / (maximum - minimum), 0, 1)
value = minimum + normalized * (maximum - minimum)
```
Choose a representative, intentionally ordinary object or scenario as the fulcrum. Validate it in common contexts before deriving a family around it.
Compare each variant with the fulcrum using outcome metrics, not raw attribute sums. Equal weighted scores are hypotheses, not proof. Cross-test extremes, counters, combinations, and options whose rules differ from the fulcrum.
### 6. Select Curves by Marginal Effect
Inspect both total values and change per step.
- Linear: constant absolute increment.
- Exponential: constant proportional increment; use for compounding or rapidly rising costs.
- Power curve: adjustable acceleration or deceleration.
- Saturating or logarithmic: large early gains followed by diminishing returns.
- Piecewise: distinct phases with explicit transition points.
Check the first, middle, last, and beyond-cap values. Plot the curve, its step-to-step difference, and time-to-earn or time-to-defeat. Keep internal precision separate from display rounding.
### 7. Model Intertwined Attributes
Reduce dependent attributes to outcome measures before comparison. Common examples:
```text
throughput = amount_per_action * actions_per_second * success_probability * uptime
time_to_goal = required_amount / net_gain_rate
expected_damage = hit_probability * damage_on_hit
effective_durability = health / (1 - damage_reduction)
```
State assumptions about reloads, downtime, overkill, target resistance, movement, resource limits, and player execution. A single composite score is useful for screening but can conceal burst, variance, reach, control, and team utility.
### 8. Model Economies and Randomness
Use [Economies and Probability](references/economies-and-probability.md) to map sources, sinks, stocks, conversions, affordability, weighted outcomes, expected value, variance, droughts, and dependent events.
For economies, calculate net flow per relevant player-time unit and by progression cohort. Check inflation, stagnation, hoarding, mandatory upkeep, and wealth concentration.
For random systems, calculate outcome probabilities, expected payout, spread, percentiles, repeated-failure probability, and dependency. Model guarantees or escalating odds as stateful systems, not independent rolls.
### 9. Check Deterministic Extremes
Before simulation or human testing, verify:
- Minimum, maximum, zero, cap, and one-step-past-cap values.
- Empty and full stocks.
- Fastest and slowest legal rates.
- Simultaneous events and tie resolution.
- Rounding boundaries.
- Impossible or invalid input handling.
- Best-case combo, worst-case combo, and self-sustaining loops.
- Start-from-zero and recovery-from-deficit behavior.
Purposefully test absurd values in an isolated copy. Extreme tests reveal hidden dependencies and engine or rule limits quickly.
### 10. Simulate Interacting Outcomes
Use simulation when analytical formulas become unwieldy because of state, policies, dependencies, or repeated randomness. Follow [Simulation, Telemetry, and Tuning](references/simulation-telemetry-and-tuning.md).
Define agent policies and skill assumptions explicitly. Run multiple deterministic seeds, report distributions and confidence, and verify simple cases analytically. A simulated agent's preferred option proves only what is optimal for that policy.
Use sensitivity sweeps to identify which inputs move outcomes most and which interactions reverse conclusions.
### 11. Playtest the Decision
Test whether players can perceive the tradeoff and use it, not merely whether model outputs are close.
Observe:
- Choice time and comparison behavior.
- Choice share conditional on availability and context.
- Strategy switching as conditions change.
- Disagreement supported by coherent reasoning.
- Options never considered or abandoned after one use.
- Prediction accuracy and perceived fairness.
- Recovery behavior after bad outcomes.
Fresh players test legibility. Experienced players test depth and optimization. Separate confusion from thoughtful hesitation.
### 12. Instrument Telemetry Before Scaling
For each metric, define the decision it informs, event, properties, denominator, cohort, and retention period. Include build and balance-data versions so results can be attributed to the correct rules.
Record opportunity as well as action. Pick rate is meaningless if the option was not offered or affordable. Record relevant state before and after an economy transaction or encounter.
Collect only necessary data, use appropriate consent and privacy practices, and do not infer player intent from one aggregate metric.
### 13. Tune as an Experiment
For each tuning pass:
1. State the diagnosed cause.
2. Choose the lowest-impact lever that can affect it.
3. Predict primary and guardrail movement.
4. Change one lever or inseparable bundle.
5. Recalculate the model and invariants.
6. Re-run deterministic cases and fixed-seed simulations.
7. Playtest or release to a controlled cohort when warranted.
8. Compare against the prior version and segments.
9. Keep, revise, roll back, or gather more evidence.
10. Record the decision and update the source of truth.
## Diagnostic Signals
- **Dominant option:** check context-adjusted outcomes, information advantage, execution cost, availability, and synergy before nerfing its headline value.
- **Unused option:** verify discoverability and eligibility, then compare its situational payoff and cognitive cost.
- **Snowball:** measure how current advantage changes future earning, denial, information, or action capacity. Add saturation, exposure, upkeep, alternate value paths, or recovery opportunities.
- **Failure spiral:** find the point where loss removes the resources needed to act. Preserve a floor or provide a costly but credible recovery path.
- **Grind:** graph time-to-goal and meaningful decisions per interval. Reduce repetition, adjust earning/cost curves, or add strategically distinct routes.
- **Inflation:** compare source and sink rates by cohort, holdings percentiles, price movement, and purchase relevance.
- **Stagnation:** check whether scarcity or fear makes saving always preferable to spending.
- **RNG frustration:** inspect failure-streak and reward-drought percentiles, not only advertised chance or mean payout.
- **Model/play mismatch:** audit omitted constraints, player execution, feedback, context mix, and implementation rounding.
- **Aggregate contradiction:** segment by skill, progression, map, mode, party, build, and exposure.
- **Telemetry jump:** check schema, balance version, population mix, event opportunity, and instrumentation before attributing it to design.
## Failure Modes
- Tuning without a measurable contract.
- Equating balance with sameness or equal popularity.
- Adding raw attributes that never affect a decision or outcome.
- Comparing unlike units without normalization or context.
- Treating a weighted score as proof of equal performance.
- Choosing a curve by appearance while ignoring marginal change and time cost.
- Hard-coding repeated constants throughout a workbook.
- Using averages that hide tails, outliers, or mixed cohorts.
- Treating dependent or guaranteed random events as independent.
- Simulating an unrealistic policy and calling the result player behavior.
- Changing several unrelated values, making attribution impossible.
- Correcting a local symptom with a global multiplier.
- Collecting telemetry without a decision, denominator, or version.
- Trusting statistically precise data that measures the wrong behavior.
- Shipping hidden adaptive difficulty that violates the game's fairness promise.
- Rounding early and allowing cumulative drift between model and implementation.
## Required Deliverables
Unless the user requests a narrower artifact, produce:
- Balance contract, player segments, contexts, horizon, and guardrails.
- Attribute/data dictionary with units, ranges, ownership, and formulas.
- Inspectable model or spreadsheet layout with centralized parameters.
- Fulcrum and representative scenario set.
- Curve, economy, and probability analysis where applicable.
- Deterministic edge checks and invariant results.
- Simulation or playtest plan with assumptions and outputs.
- Telemetry question-to-event plan.
- Ranked diagnosis with causal evidence and uncertainty.
- Tuning proposal, expected movement, rollback condition, and change log entry.
## Verification
- Targets are measurable and scoped to players, context, and time.
- Inputs, derived values, display values, and observations are distinct.
- Units are compatible, formulas are labeled, and rounding order is explicit.
- Shared constants have one authoritative location.
- Normalization round-trips at minimum, midpoint, and maximum.
- The fulcrum works in ordinary scenarios; extremes and unique rules are cross-tested.
- Curves satisfy endpoints, monotonicity or intended reversals, caps, and marginal-change goals.
- Economy stocks reconcile with sources, sinks, transfers, and starting balances.
- Probability weights normalize; expected value and tail risks are checked.
- Deterministic edge cases pass before stochastic tests.
- Simulations are reproducible, policies are documented, and results converge sufficiently for the decision.
- Telemetry records opportunity, context, version, action, and outcome without unnecessary data.
- Model predictions are compared with playtest or live evidence.
- Guardrails and regressions are checked after each change.
- The source of truth, decision record, and rollback values are current.