API ReferenceGE Extensionsgameplayrallynotebookstructured
Text Compositor
Converts structured pacenote data into human-readable text strings for co-driver audio. Handles distance rounding, unit conversions, and phrase enumeration for TTS audio generation.
Converts structured pacenote data into human-readable text strings for co-driver audio. Handles distance rounding, unit conversions, and phrase enumeration for TTS audio generation.
Constructor
local TextCompositor = require('/lua/ge/extensions/gameplay/rally/notebook/structured/textCompositor')
local tc = TextCompositor(compositorName)Public API
| Function | Signature | Returns | Description |
|---|---|---|---|
C:load | () | boolean | Loads the compositor Lua module from disk |
C:compositeText | (structured, distBefore, distAfter) | string | Composites structured data into text |
C:compositeTextEscaped | (structured, distBefore, distAfter) | string | Same as compositeText but with HTML escaping |
C:getConfig | () | table | Returns compositor configuration |
C:getBreathConfig | () | table | Returns breath timing configuration |
C:getSystemPacenotes | (missionPacenotesDirname) | table | Returns system pacenotes (countdown, finish, etc.) with audio filenames |
C:getSystemPacenote | (name, i) | table | Gets a specific system pacenote by name and variant index |
C:enumerateDistances | () | table | Lists all possible distance call strings |
C:enumeratePacenotes | () | table | Lists all possible pacenote phrases |
C:enumerateAll | () | table | Enumerates all phrases (distances + pacenotes + system) with SHA1 hashes |
C:writeEnumerated | (fname, enumerated) | nil | Writes enumerated phrases to JSON file |
C:roundDistance | (dist) | number, string | Rounds distance and returns value + unit |
C:distanceToString | (dist, forceSkipSeparateDigits) | string | Converts distance in meters to spoken string |
C:postProcessPhrase | (phrase, punctuation) | string | Applies punctuation post-processing |
C:getDistanceCallShorthand | (dist) | string | Gets shorthand text for close distances (e.g., "and") |
M.init | (compositorName) | nil | init |
M.compositorPath | () | nil | compositorPath |
M.getDistanceCallLevel1Text | () | nil | getDistanceCallLevel1Text |
M.getDistanceCallLevel2Text | () | nil | getDistanceCallLevel2Text |
M.getDistanceCallLevel3Text | () | nil | getDistanceCallLevel3Text |
M.getPointTranslation | () | nil | getPointTranslation |
M.getRoundingMediumThreshold | () | nil | getRoundingMediumThreshold |
M.getRoundingLargeThreshold | () | nil | getRoundingLargeThreshold |
Config Accessors
| Function | Returns | Description |
|---|---|---|
C:getSeparateDigits | boolean | Whether to space out digits (e.g., "1 50") |
C:getPunctuationLastNote | string | Punctuation for the last note |
C:getPunctuationDefault | string | Default phrase-end punctuation |
C:getPunctuationDistanceCalls | string | Punctuation for distance calls |
C:getDistanceCallLevel1Threshold | number | Distance threshold for level 1 ("and") |
C:getDistanceCallLevel2Threshold | number | Distance threshold for level 2 |
C:getDistanceCallLevel3Threshold | number | Distance threshold for level 3 |
C:getBaseUnit | string | Base unit translation (e.g., "meters") |
C:getLargeUnit | string | Large unit translation (e.g., "kilometers") |
C:getRoundingSmall | number | Small rounding step |
C:getRoundingMedium | number | Medium rounding step |
C:getRoundingLarge | number | Large rounding step |
How It Works
- Compositor loading: Loads a Lua module from
/lua/ge/extensions/gameplay/rally/compositors/<name>/compositor.luathat defines text rules, severity configs, and punctuation - Distance rounding: Uses three tiers (small/medium/large) with configurable thresholds to produce natural spoken distances
- Text composition: Delegates to
LibCompositor.composite()which processes structured pacenote attributes through the loaded config - Enumeration: Can enumerate all possible phrases for pre-generating TTS audio, each tagged with a SHA1 hash for audio file lookup
- System pacenotes: Manages static phrases (countdown, finish, damage) with cached audio file paths
-- Load and use a text compositor
local tc = TextCompositor("english_default")
tc:load()
-- Convert structured pacenote to text
local text = tc:compositeText(structuredData, 150, 200)
-- Convert distance to spoken string
local str = tc:distanceToString(350) -- e.g., "3 50" or "350"
-- Enumerate all phrases for TTS generation
local enumerated = tc:enumerateAll()
tc:writeEnumerated("/temp/rally/phrases.json", enumerated)See Also
- Library Compositor - Related reference
- Structured Pacenote Schema - Related reference
- VisualCompositor - Pacenote Visual Icon Generation - Related reference
- Gameplay Systems Guide - Guide
Structured Pacenote Schema
Defines the schema for structured pacenote fields - the machine-readable description format for rally corners, caution levels, modifiers, and special events. Provides field definitions with types, def
Visual Compositor
Generates visual pacenote icon data for the HUD display. Converts structured pacenote attributes (corner severity, modifiers, cautions) into icon descriptions consumed by the CEF UI layer.