Persistent Treasure Chest

Tutorial draft based on the Probability Director source documentation at CL495. No Unreal Editor screenshots are attached yet.

Give each chest deterministic loot decisions tied to its stable gameplay identity. Opening one chest should not consume a Sequential cursor that shifts the result for a different chest.

Before you begin

• Register a Probability Director Stream configured for Keyed decisions.
• Give each chest a durable ID from game data, such as Chest.Forest.0042.
• Do not use an actor pointer, transient actor name, array position, or temporary object number as the ID.
• Check the returned operation status before using a result.

See Streams and Decision Keys, the Blueprint quickstart, and the C++ quickstart for the API details.

1. Register a loot Stream

Create a long-lived Stream named Loot.World and configure its Decision Mode as Keyed. Create it once during stable game initialization and reuse it. Keep loot decisions separate from unrelated Sequential systems such as combat damage.

Probability Director owns the Stream runtime. Your game owns when chests are opened and what a rarity result means for gameplay.

2. Give each chest a stable identity

Store an ID in authored or saved gameplay data, for example Chest.Forest.0042. A level rename or a change in actor load order should not change that ID. If separate campaigns should produce separate chest outcomes, include the game’s own stable campaign identity in the subject ID.

3. Make the rarity decision

Build a Decision Key with:

Namespace: Loot
Stable Subject ID: Chest.Forest.0042
Decision: Rarity
Occurrence: 0

Use the Keyed operation for the rarity selection and handle its status. Repeating the same compatible Keyed request intentionally returns the same deterministic result.

4. Make item decisions

Use a distinct decision name for item selection. If the chest grants multiple items, assign an explicit occurrence to each pick:

Item pick	Decision	Occurrence
First	Item	0
Second	Item	1
Third	Item	2

Probability Director does not increment a hidden Keyed counter. The caller supplies every occurrence.

5. Save the gameplay result

Save resolved loot in the game’s own save data. On load, restore the chest’s gameplay result instead of resolving the chest again when the intended behavior is “this chest stays opened.” A stable Keyed identity makes repeated requests predictable; it does not store the game’s inventory, chest state, or save file.

For a new campaign, use a new stable campaign identity or the documented campaign lifecycle. Keyed decisions do not prevent editing or restoring old save files. Review persistence and security boundaries before choosing a save policy.

6. Verify the behavior

Test these cases in a development build:

1. Open chest Chest.Forest.0042 and record its checked result.
2. Open another chest first, then request the first chest’s same Keyed decision again.
3. Confirm the same chest ID, decision, and occurrence produce the same result.
4. Change only the chest ID or occurrence and confirm you are asking for a different semantic decision.
5. Inspect the registered Stream and sanitized diagnostic metadata with the Runtime Inspector; do not use Inspector output as gameplay state.

The Probability Director Lab and Monte Carlo tools are isolated analysis tools. Their experiments do not advance a gameplay Runtime Stream.

Next steps

• Learn Sequential versus Keyed decisions.
• Review persistence policies and anti-save-scumming patterns.
• Use Resolution Rules Data Assets for reusable numeric dice configuration.