Library Compositor

Core composition engine that converts structured pacenote fields into human-readable text phrases. Handles corner calls, caution phrases, modifiers, distance calls, finish lines, and phrase enumeration for TTS generation. Also provides weighted random selection for system pacenotes.

Public API

Internals

Composition Pipeline (M.composite)

1. Collect variables from structured fields + config lookups
2. Build phrases in order:
   • Caution phrase (e.g., "caution" / "double caution")
   • Corner phrase (e.g., "4 right long tightens,")
   • Modifier phrases (e.g., "don't cut", "bumpy", "crest") - max 3
   • Finish line phrase
   • Distance after (e.g., "50,")
3. Each phrase is post-processed (trimmed + punctuated)
4. Returns array of strings (one per sub-phrase for TTS)

Variable Collection

Corner Phrase Assembly

[distanceBefore] cornerSeverity cornerDirection [cornerLength] [cornerRadiusChange]

Example: "50 4 right long tightens,"

getNearestValue

Used for cornerSeverity, cornerLength, cornerRadiusChange - finds closest matching entry from config values list:

for _, entry in ipairs(valuesList) do
  local diff = math.abs(entry.value - targetValue)
  -- track closest
end

Modifier Priority

Modifiers are sorted by priority field from config and limited to 3 max. First modifier can use textWhenFirst variant.

Enumeration (M.enumerate)

Generates all valid phrase combinations by iterating:

• All caution levels × distance variants
• All corner severity × direction × length × radius change × distance variants
• All square corners × direction × length × radius change
• All individual modifiers × distance variants
• Finish line text

Used to pre-generate TTS audio files for the offline structured audio mode.

Weighted Random Selection

M.getRandomWeightedItem(items)
-- Normalizes weights, generates random 0-1, walks cumulative distribution
-- Default weight = 1 if not specified

How It Works

1. Text compositor loads a language-specific config (corner names, modifier texts, punctuation)
2. composite() maps structured field values → config lookups → phrase strings
3. Distance calls ($db, $da) can be escaped for later interpolation or resolved immediately
4. enumerate() produces all possible phrases for TTS pre-generation
5. getRandomWeightedItem() selects system pacenotes (go, countdown, damage) with weight distribution

Usage Example

local LibCompositor = require('gameplay/rally/notebook/structured/libCompositor')

-- Compose a structured pacenote
local phrases = LibCompositor.composite(config, structured, "50", "into")
-- {"50 4 right long,", "don't cut,", "into,"}

-- Enumerate all phrases for TTS generation
local allPhrases = LibCompositor.enumerate(textCompositor, config)

-- Pick weighted random system pacenote
local item = LibCompositor.getRandomWeightedItem(noteSet)

See Also

• Structured Pacenote Schema - Related reference
• TextCompositor - Structured Pacenote Text Generation - Related reference
• VisualCompositor - Pacenote Visual Icon Generation - Related reference
• Gameplay Systems Guide - Guide