Coins

Probability Director models coin behavior through the same exact Bernoulli/Binomial probability system used elsewhere in the plugin.

A coin does not require a duplicate Runtime distribution type.

This document describes the Coin concept: fair coins, Heads probability, exact Heads-count distributions, Bias, gameplay API selection, and deterministic sampling.

For the Editor workflow, Automatic Flips, charts, empirical results, and exports, see Lab-Coin.md.

1. Purpose

Coin mechanics are useful when gameplay has two outcomes:

Heads / Tails
Success / Failure
Yes / No
On / Off

A fair coin is:

P(Heads) = 1/2
P(Tails) = 1/2

In Probability Director, one coin is naturally Bernoulli.

Multiple independent coins produce a Binomial Heads-count distribution.

2. One Coin

Let:

p = P(Heads)

Then:

P(Tails) = 1 - p

A fair coin uses:

p = 1/2

The underlying probability can be represented exactly.

3. Multiple Coins

For N independent coins using the same Heads probability, the number of Heads follows a Binomial distribution.

Support:

0 ... N Heads

For two fair coins:

Heads	Exact probability
0	1/4
1	1/2
2	1/4

This exact Heads-count PMF is the natural mathematical basis of Coin Lab.

4. Coin Bias

Coin Bias changes the probability toward:

Heads.
Tails.
Neutral.

Neutral preserves:

P(Heads) = 1/2

Bias Toward Heads increases Heads probability.

Bias Toward Tails decreases Heads probability.

The exact Probability Director probability-Bias contract remains authoritative.

5. Coin Bias vs. Dice Bias

Dice Bias reshapes ordered numeric face support.

Coin Bias changes a two-outcome probability.

For coin-like gameplay, use Bernoulli/Probability Bias semantics instead of creating a numeric two-face die solely to gain Dice Bias.

6. Exact Probability

Probability Director can preserve the fair probability exactly as:

1 / 2

and derive exact Heads-count probabilities for the supported bounded Binomial system.

Displayed decimals are presentation only.

7. Gameplay Runtime API

Coin functionality is fulfilled through existing Bernoulli/Binomial Runtime and exact math.

Use:

Bernoulli for one coin/event.
Binomial for the number of Heads/successes across fixed repeated independent trials.

No duplicate Coin Runtime distribution type is necessary.

8. Sequential Sampling

For call-order-driven gameplay:

Create/select a Sequential Probability Director Stream.
Sample Bernoulli or Binomial through the normal Runtime API.

A Fixed Seed can reproduce the compatible sequence.

A Secure Stream provides fresh Runtime unpredictability.

9. Keyed Sampling

For a stable semantic coin decision:

Use a Keyed Stream.
Supply an explicit Decision Key.
Supply explicit Occurrence.

Example:

Namespace: QuestReward
Stable Subject ID: Chest.0042
Decision: BonusCoin
Occurrence: 0

Keyed sampling does not advance Sequential state.

10. Heads Count vs. Flip Sequence

For multiple coins, the analyzed random variable is usually:

Number of Heads

not the chronological string of individual flip results.

For N coins:

0 ... N

is the count support.

If a game needs the chronological individual sequence, perform/record the individual gameplay operations. Do not infer chronology from a Heads-count PMF.

11. Probability vs. Coin Terminology

Coin terminology is a convenient presentation:

Heads
Tails
Coins
Flips

The underlying mathematics remain:

Bernoulli
Binomial
Probability Bias
Empirical sampling

This keeps one source of probability truth.

12. Error Handling

Coin-like gameplay inherits the normal Probability/Distribution failure model.

Possible failures include:

Invalid probability.
Invalid trial count.
Invalid Stream.
Decision-mode mismatch.
Invalid Decision Key.
Numerical/sampling failure where applicable.

Always inspect the structured result/status.

13. API Selection Guide

Need	Use
One fair coin	Bernoulli `p = 1/2`
One biased coin	Bernoulli with configured exact probability
Number of Heads from fixed coins	Binomial
Repeated call-order-driven gameplay	Sequential
Stable semantic coin result	Keyed
Editor coin visualization	Coin Lab
General probability balancing	Probability Director Lab

14. Recommended Patterns

Use Bernoulli directly for a generic chance

If the gameplay rule is simply:

35% chance to happen

you do not need a Coin-specific gameplay abstraction.

Use the Probability/Distribution API.

Use Coin Lab for intuitive analysis

The Coin metaphor is useful when developers/designers want an immediately understandable two-outcome experiment.

Keep probability and Seed Source separate

A fair coin can use either Fixed or Secure randomness.

Fairness and Secure randomness are different concepts.

15. Public Safety Boundaries

Coin/Bernoulli sampling does not expose:

Raw RNG bytes.
Secure root.
Entropy bytes.
Generator key/nonce.
Raw generator state.
Byte position.
Persistence secret state.

Heads/Tails or success-count results are public gameplay outputs.

16. Common Mistakes

Creating a separate PRNG just for coins

Use a Probability Director Stream.

Treating Heads-count PMF as flip chronology

It only describes the count.

Assuming Secure means “more fair”

Seed source and event probability are independent.

Treating Coin Bias as an additive result modifier

Bias changes probability.