Markov Models and Name Generation

Probability Director provides a finite-state weighted Markov system and a cooked Runtime UProbabilityNameModel for deterministic or secure procedural name generation.

The Name Model supports two V1 generation methods:

N-Gram Markov
Weighted Syllables

This document describes the Runtime concepts, deterministic compilation rules, exact analysis, Sequential/Keyed generation, batch convenience APIs, limits, and failure behavior.

For the Editor workflow, see Lab-Name.md.

1. Purpose

Use the Markov/Name system when you need:

Data-driven procedural names.
Fixed-Seed reproducibility.
Stable Keyed generation.
Secure isolated batch generation.
Deterministic model compilation.
Exact Markov transition analysis.
Exact weighted syllable-role analysis.
Bounded generation with structured failure.

Typical uses include:

Character names.
Place names.
Item names.
Faction names.
Procedural labels.

2. Generic Weighted Markov Model

Probability Director Runtime includes a finite-state weighted Markov model.

Public states use stable FName identities.

Each transition contains:

Destination state.
Positive integer weight.

Terminal states are explicit.

3. Compilation Validation

Compilation rejects invalid models including:

Empty models.
Invalid states.
Duplicate state definitions.
Non-positive transition weights.
Missing destinations.
Unmarked accidental terminals.
Checked weight overflow.
Configured work-limit violations.

Invalid input is not silently repaired into different semantics.

4. Deterministic Canonicalization

Compilation canonicalizes:

States lexically.
Each state’s destination transitions lexically.

Duplicate transitions to the same destination are merged with checked exact weight addition.

These do not define the compiled random semantics:

Authoring row order.
Map iteration order.
Pointer addresses.
Hash bucket order.

Lexical order is a deterministic serialization/canonicalization rule, not a mathematical ranking of states.

5. Analyze Markov State

AnalyzeMarkovState is pure.

It consumes no RNG.

It can return:

Canonical destination identities.
Exact integer weights.
Exact weight / total weight probabilities.
Total outgoing weight.
Structured status.

Displayed decimals are presentation only.

V1 does not turn this API into a general matrix-exponentiation or stationary-distribution framework.

6. Sequential Markov Sampling

Sequential transition sampling uses the selected registered Probability Director Sequential stream and unbiased bounded integer generation.

A one-destination state uses bound-one behavior and consumes no unnecessary RNG bytes.

Use Sequential transition sampling when call order is intentionally part of the random sequence.

7. Keyed Markov Sampling

Keyed transition sampling uses:

Registered Keyed stream.
Explicit DecisionKey.
Explicit caller-supplied Occurrence.

There is no hidden Markov cursor.

There is no hidden occurrence counter.

The same compatible model/key/occurrence reproduces the same semantic transition.

8. Probability Name Model

UProbabilityNameModel is a cooked Runtime UDataAsset.

It stores authored generation data, not RNG state.

Common fields/concepts include:

Generation Method.
Purpose metadata.
Method-specific authoring.
Maximum Generated Characters.

Generation Method:

N-Gram Markov.
Weighted Syllables.

Purpose metadata may classify intended use such as:

General.
Character.
Item.
Place.

Purpose is metadata only and does not alter random semantics.

9. N-Gram Markov Names

N-Gram generation learns next-character frequencies from training strings.

Supported Order:

1 ... 4

Default:

Order N means the next UTF-16 character unit is selected from frequencies learned for exactly N preceding units.

10. Start and End Boundaries

Internal start markers pad the initial context.

An internal terminal state represents natural termination.

These are internal model symbols.

They are not user-enterable magic characters.

11. Training String Processing

The N-Gram compiler:

Trims outer whitespace.
Ignores strings empty after trim.
Preserves case.
Preserves punctuation.
Preserves apostrophes.
Preserves hyphens.
Preserves internal spaces.
Performs no locale-dependent normalization/case conversion.

Duplicate training strings intentionally add frequency.

12. N-Gram Determinism

Equivalent authored data compiles deterministically.

Reordering training rows does not create a new accidental hash/array-order RNG contract.

Fixed-Seed generation remains reproducible when:

Model data is equivalent.
Runtime deterministic contract is compatible.
The same sequence of Sequential operations occurs.

13. N-Gram Bounds

Item	V1 limit
Authored training strings	2,048
UTF-16 units per training string	128
Compiled states	4,096
Canonical transitions	16,384
Markov Order	1–4
Generated characters	1–128

Exceeding a bound fails.

Data is never silently truncated/reduced merely to fit.

14. N-Gram Generation Bound

A successful generated name must reach the learned natural end transition.

If Maximum Generated Characters is reached first:

GenerationBoundReached

is returned.

The partial string is not silently reported as a successful truncated name.

Probability Director does not retry-until-pretty.

15. Weighted Syllables

Weighted Syllables is an explicit second Name Model method.

Each entry contains:

Authored FString text.
One positional Role.
Positive exact integer weight.

Roles:

Single.
Start.
Middle.
End.

16. Syllable Text Rules

The compiler:

Trims outer whitespace.
Preserves case.
Preserves punctuation.
Preserves apostrophes.
Preserves hyphens.
Preserves internal whitespace.

No separator is inserted automatically.

If a separator is desired, author it into the syllable text.

17. Syllable Count

Configured inclusive range:

1 ... 8 syllables

Role structure:

1:
Single

2:
Start + End

3+:
Start + Middle... + End

If the range varies, count selection is uniform and exact.

If the range is fixed, no count-selection draw is required.

18. Role Validation

Compilation validates every role needed by every possible configured count.

It never silently changes the requested syllable range.

Examples of failure:

Missing Single.
Missing Start.
Missing End.
Missing Middle when 3+ syllables are possible.
Empty syllable.
Non-positive weight.
Weight overflow.
Invalid min/max.

19. Duplicate Syllables

Within one Role:

Duplicate text is merged.
Weight is summed with checked arithmetic.
Canonical serialization order is deterministic.

Identical text in different Roles remains independent.

20. Analyze Name Model

AnalyzeNameModel is pure.

It consumes no RNG.

For N-Gram, it can report compilation/model summary.

For Weighted Syllables, it can report:

Exact uniform count distribution.
Exact per-role weight / total weight entries.

It does not enumerate all possible full names.

21. Sequential Name Generation

GenerateNameSequential uses a registered Sequential Probability Director stream.

Seed Source determines behavior:

Fixed -> reproducible compatible sequence.
Secure -> Probability Director Secure randomness.

Sequential generation advances the selected Stream according to the actual required draws.

22. Keyed Name Generation

GenerateNameKeyed uses:

Registered Keyed Stream.
Explicit Decision Key.
Explicit Occurrence.

Each character/syllable decision derives stable subdecision identity from that request.

There is no persistent Name cursor and no hidden occurrence.

23. N-Gram Keyed Step Identity

Character transitions derive deterministic per-step roles conceptually equivalent to:

NameTransition.step

The caller supplies the logical Decision Key.

Probability Director derives bounded per-step identities internally.

24. Weighted Syllable Keyed Identity

Weighted Syllable generation derives distinct subdecisions for concepts such as:

NameSyllableCount
NameSyllable.index

No hidden keyed cursor is persisted.

25. Runtime Batch Convenience APIs

Simple gameplay-facing APIs include:

GenerateNGramNames(NameModel, NumberOfNames)
GenerateWeightedSyllableNames(NameModel, NumberOfNames)

Default:

NumberOfNames = 1

Bound:

1 ... 256

Ordered TArray<FString> results preserve output order.

Duplicate generated names are allowed.

26. Method Matching

The selected convenience API must match the model Generation Method.

Example:

N-Gram model
+ GenerateNGramNames
= valid

Weighted Syllables model
+ GenerateNGramNames
= structured failure

Probability Director does not silently change the requested method.

27. Batch Random Context

The simple batch facade creates a temporary Runtime Secure Sequential context.

It does not:

Consume unrelated gameplay Sequential streams.
Require PIE.
Require Editor/Slate.
Expose Secure state.
Provide Fixed-Seed replay controls.

Use explicit Sequential/Keyed Name APIs when gameplay stream identity/determinism matters.

28. Batch Atomicity

Batch generation is all-or-nothing.

If any requested name fails, Probability Director does not secretly reroll replacements until the requested count is filled.

It does not present a hidden retry-generated batch as though the original request succeeded normally.

29. Blueprint API

Blueprint Runtime nodes include:

Analyze Markov State.
Sample Markov Transition Sequential.
Sample Markov Transition Keyed.
Analyze Name Model.
Generate Name Sequential.
Generate Name Keyed.
Generate N-Gram Names.
Generate Weighted Syllable Names.

All return structured public result/status data.

30. C++ Convenience Example

FProbabilityNameBatchResult Result =
    ProbabilityDirector->GenerateNGramNames(NameModel, 8);

// Check Result.Status and generated/requested counts before accepting the batch.

31. Explicit Stream Pattern

Conceptually:

// Sequential:
GenerateNameSequential(StreamId, NameModel, ...);

// Keyed:
GenerateNameKeyed(StreamId, DecisionKey, NameModel, ...);

Use explicit stream generation when generated names are part of gameplay deterministic state.

32. Length Failure

For both generation methods, output length is checked.

If generation/assembly would exceed Maximum Generated Characters:

Structured failure is returned.
No silent truncation.
No hidden retry.

33. API Selection Guide

Need	Use
Inspect one generic Markov state	Analyze Markov State
Sample next state in changing sequence	Sequential Markov
Stable semantic transition	Keyed Markov
Name from gameplay stream	Generate Name Sequential
Stable semantic name	Generate Name Keyed
Simple secure N-Gram batch	Generate N-Gram Names
Simple secure syllable batch	Generate Weighted Syllable Names
Editor experimentation	Name Lab

34. Public Safety Boundaries

Name/Markov APIs do not expose:

Secure root.
Entropy bytes.
Generator key.
Nonce.
Raw generator state.
Byte position.
Persistence secret state.

Generated names/transitions are public outputs.

Secure generator state remains private.

35. Common Mistakes

Treating authoring order as probability order

Compilation canonicalizes deterministically.

Expecting retry-until-pretty

Probability Director does not do that.

Expecting convenience batch generation to be reproducible

It intentionally uses an isolated Secure context. Use explicit Fixed Sequential or Keyed generation for determinism.

Expecting the generation bound to truncate successfully

It returns failure.

Expecting automatic syllabification

Weighted Syllables uses explicit authored syllables/roles.

36. Outside V1 Scope

V1 does not include:

Full Markov matrix exponentiation.
Stationary-distribution analysis.
Complete-name PMF enumeration.
Automatic linguistic syllabification.
Automatic separators.
Whole-model graph visualization as a Runtime requirement.