ludus::content::procedural¶
Ludus Wiki · API overview · Browse API
Namespace
Related declarations¶
- ludus::content::procedural::ScatterIdentity
- ludus::content::procedural::ScatterRectangle
- ludus::content::procedural::ScatterCellRange
- ludus::content::procedural::ScatterVariant
- ludus::content::procedural::ScatterLayer
- ludus::content::procedural::ScatterRecipe
- ludus::content::procedural::ScatterDomains
- ludus::content::procedural::ScatterKeys
- ludus::content::procedural::ScatterPlacement
- ludus::content::procedural::ScatterValidation
Enumerations¶
ScatterStatus¶
enum class ScatterStatus : uint8
Result of a scatter operation.
Related types: uint8
Success¶
Success
The operation succeeded.
InvalidRecipe¶
InvalidRecipe
The recipe, domains or a layer index failed validation.
InvalidRange¶
InvalidRange
A cell range is empty or lies outside the layer's cells.
CapacityExceeded¶
CapacityExceeded
The caller's storage cannot hold every candidate of the range.
SamplingExhausted¶
SamplingExhausted
A bounded draw exhausted its 65,536 attempts.
ScatterRecipeIssue¶
enum class ScatterRecipeIssue : uint8
The specific problem validation found.
Related types: uint8
None¶
None
No problem.
RoomZero¶
RoomZero
The room ordinal is zero.
EmptyRegion¶
EmptyRegion
The region is empty.
KeepOutCount¶
KeepOutCount
The keep-out view is invalid or has too many entries.
EmptyKeepOut¶
EmptyKeepOut
A keep-out rectangle is empty; Index names it.
LayerCount¶
LayerCount
The layer view is invalid, empty or has too many entries.
DuplicateLayer¶
DuplicateLayer
A layer repeats an earlier layer's ID; Index names the later layer.
CellSize¶
CellSize
A layer's cell size is zero; Index names it.
CellRange¶
CellRange
A layer's region cells do not fit int16 coordinates; Index names it.
CandidateCount¶
CandidateCount
A layer's candidate count is zero or too large; Index names it.
VariantCount¶
VariantCount
A layer's variant view is invalid, empty or has too many entries; Index names it.
ExclusionRadius¶
ExclusionRadius
A variant's exclusion radius exceeds its layer's cell size; Index names the layer.
ScaleRange¶
ScaleRange
A layer's maximum scale is below its minimum; Index names it.
Domain¶
Domain
A domain ID is outside the game range or repeats another scatter domain.
Constants and variables¶
SCATTER_LAYOUT_VERSION¶
constexpr uint32 ludus::content::procedural::SCATTER_LAYOUT_VERSION = 1
Version of the placement identity packing and random layout below; store it with generated content.
Related types: uint32
MAX_SCATTER_LAYERS¶
constexpr usize ludus::content::procedural::MAX_SCATTER_LAYERS = 16
Most layers in one recipe.
Related types: usize
MAX_SCATTER_KEEP_OUTS¶
constexpr usize ludus::content::procedural::MAX_SCATTER_KEEP_OUTS = 64
Most keep-out rectangles in one recipe.
Related types: usize
MAX_SCATTER_VARIANTS¶
constexpr usize ludus::content::procedural::MAX_SCATTER_VARIANTS = 64
Most variants in one layer.
Related types: usize
MAX_SCATTER_CANDIDATES_PER_CELL¶
constexpr uint16 ludus::content::procedural::MAX_SCATTER_CANDIDATES_PER_CELL = 64
Most candidates in one cell; candidate indices are stored in 8 bits.
Related types: uint16
SCATTER_NEIGHBOR_CELLS¶
constexpr int32 ludus::content::procedural::SCATTER_NEIGHBOR_CELLS = 2
Cells searched in each direction for conflicts; follows from exclusion radius <= cell size.
Related types: int32
SCATTER_SCOPE_ROOM_SHIFT¶
constexpr uint32 ludus::content::procedural::SCATTER_SCOPE_ROOM_SHIFT = 48U
Bit position of the room in a packed address scope.
Related types: uint32
SCATTER_SCOPE_LAYER_SHIFT¶
constexpr uint32 ludus::content::procedural::SCATTER_SCOPE_LAYER_SHIFT = 40U
Bit position of the layer in a packed address scope.
Related types: uint32
SCATTER_SCOPE_CANDIDATE_SHIFT¶
constexpr uint32 ludus::content::procedural::SCATTER_SCOPE_CANDIDATE_SHIFT = 32U
Bit position of the candidate in a packed address scope.
Related types: uint32
SCATTER_SCOPE_CELL_X_SHIFT¶
constexpr uint32 ludus::content::procedural::SCATTER_SCOPE_CELL_X_SHIFT = 16U
Bit position of cell X in a packed address scope; cell Y occupies the low 16 bits.
Related types: uint32
DEFAULT_SCATTER_SCALE¶
constexpr uint16 ludus::content::procedural::DEFAULT_SCATTER_SCALE = 1000
Default layer scale: one in thousandths, the example unit of ScatterLayer::MinimumScale.
Related types: uint16
Functions¶
PackScatterScope¶
constexpr uint64 ludus::content::procedural::PackScatterScope(ScatterIdentity identity) noexcept
Pack an identity into an address scope: room, layer, candidate, cell X, cell Y from the high bits.
Related types: uint64 · ScatterIdentity
UnpackScatterScope¶
constexpr ScatterIdentity ludus::content::procedural::UnpackScatterScope(uint64 scope) noexcept
Inverse of PackScatterScope for every 64-bit value.
Related types: uint64 · ScatterIdentity
ValidateScatterRecipe¶
ScatterValidation ludus::content::procedural::ValidateScatterRecipe(const ScatterRecipe &recipe) noexcept
Check a recipe before generation. Pure and allocation-free.
Related types: ScatterRecipe · ScatterValidation
TryMakeScatterKeys¶
ScatterStatus ludus::content::procedural::TryMakeScatterKeys(uint64 worldSeed, ScatterDomains domains, ScatterKeys &outKeys) noexcept
Derive the three scatter keys from a world seed.
| Parameter | Description |
|---|---|
worldSeed |
The session's recorded root seed; zero is a valid deterministic seed.
|
domains |
Distinct IDs in the game domain range.
|
outKeys |
Written on success; unchanged on failure.
|
Returns
Success, or InvalidRecipe when a domain is out of range or repeated.
Related types: ScatterStatus · uint64 · ScatterDomains · ScatterKeys
TryGetScatterCells¶
ScatterStatus ludus::content::procedural::TryGetScatterCells(const ScatterRecipe &recipe, usize layerIndex, ScatterCellRange &outCells) noexcept
Every cell of a layer whose area overlaps the region.
| Parameter | Description |
|---|---|
recipe |
The room's recipe; validated by this call.
|
layerIndex |
Index into recipe.Layers.
|
outCells |
Written on success; unchanged on failure.
|
Returns
Success, or InvalidRecipe when the recipe is invalid or layerIndex is out of bounds.
Related types: ScatterStatus · usize · ScatterCellRange · ScatterRecipe
TryCountScatterCandidates¶
ScatterStatus ludus::content::procedural::TryCountScatterCandidates(const ScatterRecipe &recipe, usize layerIndex, ScatterCellRange cells, usize &outCount) noexcept
Storage TryGenerateScatter needs for a range: its cell count times the layer's candidate count.
| Parameter | Description |
|---|---|
recipe |
The room's recipe; validated by this call.
|
layerIndex |
Index into recipe.Layers.
|
cells |
A nonempty range inside TryGetScatterCells.
|
outCount |
Written on success; unchanged on failure.
|
Returns
Success, InvalidRecipe or InvalidRange.
Related types: ScatterStatus · usize · ScatterCellRange · ScatterRecipe
TryGenerateScatter¶
ScatterStatus ludus::content::procedural::TryGenerateScatter(const ScatterRecipe &recipe, const ScatterKeys &keys, usize layerIndex, ScatterCellRange cells, foundation::BorrowedView< ScatterPlacement > storage, usize &outCount) noexcept
Generate the accepted placements of one layer in a range of cells.
Placements are written in canonical order: cell Y, then cell X, then candidate, ascending. Acceptance depends only on placement identities, never on the range, so generating a layer's cells in several ranges and joining the results in canonical order equals one call over all of them. Neighbouring cells outside the range are evaluated but never written. Pure, allocation-free and safe to call concurrently on distinct storage.
| Parameter | Description |
|---|---|
recipe |
A recipe that passes ValidateScatterRecipe.
|
keys |
Keys from TryMakeScatterKeys.
|
layerIndex |
Index into recipe.Layers.
|
cells |
A nonempty range inside TryGetScatterCells.
|
storage |
Receives the placements; must hold TryCountScatterCandidates elements.
|
outCount |
Number of placements written, on success; unchanged on failure.
|
Returns
Success; InvalidRecipe, InvalidRange or CapacityExceeded before anything is written; or SamplingExhausted, after which the storage contents are unspecified.
Related types: foundation::BorrowedView · ScatterStatus · usize · ScatterCellRange · ScatterKeys · ScatterPlacement · ScatterRecipe
Aliases¶
int16¶
using ludus::foundation::core::int16 = std::int16_t
Exact 16-bit signed integer for explicit-width values.
int32¶
using ludus::foundation::core::int32 = std::int32_t
Exact 32-bit signed integer for explicit-width values.
uint16¶
using ludus::foundation::core::uint16 = std::uint16_t
Exact 16-bit unsigned integer for explicit-width values.
uint32¶
using ludus::foundation::core::uint32 = std::uint32_t
Exact 32-bit unsigned integer for explicit-width values.
uint64¶
using ludus::foundation::core::uint64 = std::uint64_t
Exact 64-bit unsigned integer for explicit-width values.
uint8¶
using ludus::foundation::core::uint8 = std::uint8_t
Exact 8-bit unsigned integer for explicit-width values.
usize¶
using ludus::foundation::core::usize = std::size_t
Native unsigned size/index type; matches sizeof and container sizes, not a wire format.