Notebook Path

Core class representing a rally notebook - the container for pacenotes, codrivers, and all rally authoring data. Manages saving/loading from JSON, codriver selection, audio mode, pacenote generation,

Core class representing a rally notebook - the container for pacenotes, codrivers, and all rally authoring data. Manages saving/loading from JSON, codriver selection, audio mode, pacenote generation, distance call autofill, debug drawing, and text/visual compositors.

Constructor

local Notebook = require('gameplay/rally/notebook/path')
local nb = Notebook(name)

Public API (Key Methods)

Lifecycle

Method	Signature	Returns	Description
`save`	`(fname?)`	`boolean`	Saves notebook to JSON file
`reload`	`()`	`nil`	Reloads from current filename
`setFname`	`(newFname)`	`nil`	Sets the file path

Codrivers

Method	Signature	Returns	Description
`selectedCodriver`	`()`	`object`	Returns active codriver from mission settings
`selectedCodriverLanguage`	`()`	`string`	Language of active codriver
`useCodriver`	`(codriver)`	`nil`	Sets active codriver by pk in mission settings
`getCodriverByPk`	`(pk)`	`object\|nil`	Finds codriver by persistent key
`getCodriverByName`	`(name)`	`object\|nil`	Finds codriver by name
`getFirstCodriver`	`()`	`object`	Returns first codriver in sorted list
`getLanguages`	`()`	`table`	Returns unique languages with associated codrivers

Pacenotes

Method	Signature	Returns	Description
`hasAnyPacenotes`	`()`	`boolean`	True if notebook has pacenotes
`deleteAllPacenotes`	`()`	`nil`	Removes all pacenotes
`appendPacenotes`	`(pacenotes)`	`nil`	Adds pacenotes from serialized data
`generatePacenotes`	`(corners)`	`nil`	Creates pacenotes from detected corners
`autofillDistanceCalls`	`()`	`nil`	Computes between-pacenote distance calls
`cacheCompiledPacenotes`	`()`	`nil`	Pre-compiles all pacenotes for playback
`sortPacenotesByName`	`()`	`nil`	Sorts pacenotes by numeric name suffix
`cleanupPacenoteNames`	`()`	`nil`	Re-indexes pacenote names sequentially

Audio

Method	Signature	Returns	Description
`getAudioMode`	`()`	`enum`	Notebook-level audio mode
`setAudioMode`	`(mode)`	`nil`	Sets audio mode
`getTextCompositor`	`()`	`object`	Returns language-specific text compositor
`getVisualCompositor2`	`()`	`object`	Returns visual compositor for HUD

Drawing

Method	Signature	Returns	Description
`drawDebugNotebook`	`(toolsState, opacity)`	`nil`	Draws all pacenotes with selection context
`drawDebugNotebookForPartitionAllSnaproad`	`(toolsState, opacity)`	`nil`	Draws for snaproad partitioning mode

Mission Integration

Method	Signature	Returns	Description
`getMissionDir`	`()`	`string\|nil`	Extracts mission directory from notebook path
`getMissionId`	`()`	`string\|nil`	Extracts mission ID (e.g., "gridmap_v2/rallyStage/test")
`missionSettings`	`()`	`object`	Returns (cached) MissionSettings instance

Internals

File Format (v3)

{
  name = "Primary",
  version = "3",
  description = "",
  authors = "",
  created_at = timestamp,
  updated_at = timestamp,
  audioMode = enum,
  codrivers = { ... },      -- serialized sortedList
  pacenotes = { ... },      -- serialized sortedList
  systemPacenotes = { ... } -- auto-generated from text compositor
}

Autofill Distance Calls

Iterates sorted pacenotes, computing driveline distance between consecutive CE→CS waypoints:

Short distances → shorthand text (e.g., "into", "and")
Normal distances → numeric string (e.g., "50")
Respects isolate and ignoreDistanceCalls flags
Uses autofill_blocker sentinel to prevent auto-fill

Pacenote Generation

generatePacenotes(corners) pipeline:

Clears existing pacenotes
Creates pacenote + CS/CE waypoints for each non-straight corner
Sets waypoint normals from snaproad if available
Sorts and cleans up names
Autofills distance calls

Drawing Modes

No selection: All pacenotes as rainbow-colored spheres
Selected: Full detail on selected + background context for neighbors
Partitioned: All pacenotes with adjacent styling for snaproad editing

Version Migration

V2→V3 upgrade converts notes[lang].note from string to {freeform, structured} object and runs autofill.

How It Works

Notebook is the top-level container loaded from *.notebook.json
Contains codrivers (language/voice configs) and pacenotes (notes + waypoints)
Active codriver determines language for text/audio composition
Text compositor converts structured fields → human-readable note strings
Visual compositor generates HUD display data from structured fields
System pacenotes (countdown, damage, etc.) are auto-generated from compositor config

Usage Example

local Notebook = require('gameplay/rally/notebook/path')
local nb = Notebook("My Rally")
nb:setFname("/path/to/primary.notebook.json")
nb:save()

-- Load and use
nb:reload()
local codriver = nb:selectedCodriver()
local lang = nb:selectedCodriverLanguage()

-- Generate pacenotes from corners
nb:generatePacenotes(detectedCorners)
nb:autofillDistanceCalls()
nb:cacheCompiledPacenotes()
nb:save()

Constructor

local Notebook = require('gameplay/rally/notebook/path')
local nb = Notebook(name)

Public API (Key Methods)

Lifecycle

Method	Signature	Returns	Description
`save`	`(fname?)`	`boolean`	Saves notebook to JSON file
`reload`	`()`	`nil`	Reloads from current filename
`setFname`	`(newFname)`	`nil`	Sets the file path

Codrivers

Method	Signature	Returns	Description
`selectedCodriver`	`()`	`object`	Returns active codriver from mission settings
`selectedCodriverLanguage`	`()`	`string`	Language of active codriver
`useCodriver`	`(codriver)`	`nil`	Sets active codriver by pk in mission settings
`getCodriverByPk`	`(pk)`	`object\|nil`	Finds codriver by persistent key
`getCodriverByName`	`(name)`	`object\|nil`	Finds codriver by name
`getFirstCodriver`	`()`	`object`	Returns first codriver in sorted list
`getLanguages`	`()`	`table`	Returns unique languages with associated codrivers

Pacenotes

Method	Signature	Returns	Description
`hasAnyPacenotes`	`()`	`boolean`	True if notebook has pacenotes
`deleteAllPacenotes`	`()`	`nil`	Removes all pacenotes
`appendPacenotes`	`(pacenotes)`	`nil`	Adds pacenotes from serialized data
`generatePacenotes`	`(corners)`	`nil`	Creates pacenotes from detected corners
`autofillDistanceCalls`	`()`	`nil`	Computes between-pacenote distance calls
`cacheCompiledPacenotes`	`()`	`nil`	Pre-compiles all pacenotes for playback
`sortPacenotesByName`	`()`	`nil`	Sorts pacenotes by numeric name suffix
`cleanupPacenoteNames`	`()`	`nil`	Re-indexes pacenote names sequentially

Audio

Method	Signature	Returns	Description
`getAudioMode`	`()`	`enum`	Notebook-level audio mode
`setAudioMode`	`(mode)`	`nil`	Sets audio mode
`getTextCompositor`	`()`	`object`	Returns language-specific text compositor
`getVisualCompositor2`	`()`	`object`	Returns visual compositor for HUD

Drawing

Method	Signature	Returns	Description
`drawDebugNotebook`	`(toolsState, opacity)`	`nil`	Draws all pacenotes with selection context
`drawDebugNotebookForPartitionAllSnaproad`	`(toolsState, opacity)`	`nil`	Draws for snaproad partitioning mode

Mission Integration

Method	Signature	Returns	Description
`getMissionDir`	`()`	`string\|nil`	Extracts mission directory from notebook path
`getMissionId`	`()`	`string\|nil`	Extracts mission ID (e.g., "gridmap_v2/rallyStage/test")
`missionSettings`	`()`	`object`	Returns (cached) MissionSettings instance

Internals

File Format (v3)

{
  name = "Primary",
  version = "3",
  description = "",
  authors = "",
  created_at = timestamp,
  updated_at = timestamp,
  audioMode = enum,
  codrivers = { ... },      -- serialized sortedList
  pacenotes = { ... },      -- serialized sortedList
  systemPacenotes = { ... } -- auto-generated from text compositor
}

Autofill Distance Calls

Iterates sorted pacenotes, computing driveline distance between consecutive CE→CS waypoints:

Short distances → shorthand text (e.g., "into", "and")
Normal distances → numeric string (e.g., "50")
Respects isolate and ignoreDistanceCalls flags
Uses autofill_blocker sentinel to prevent auto-fill

Pacenote Generation

generatePacenotes(corners) pipeline:

Clears existing pacenotes
Creates pacenote + CS/CE waypoints for each non-straight corner
Sets waypoint normals from snaproad if available
Sorts and cleans up names
Autofills distance calls

Drawing Modes

No selection: All pacenotes as rainbow-colored spheres
Selected: Full detail on selected + background context for neighbors
Partitioned: All pacenotes with adjacent styling for snaproad editing

Version Migration

V2→V3 upgrade converts notes[lang].note from string to {freeform, structured} object and runs autofill.

How It Works

Notebook is the top-level container loaded from *.notebook.json
Contains codrivers (language/voice configs) and pacenotes (notes + waypoints)
Active codriver determines language for text/audio composition
Text compositor converts structured fields → human-readable note strings
Visual compositor generates HUD display data from structured fields
System pacenotes (countdown, damage, etc.) are auto-generated from compositor config

Usage Example

local Notebook = require('gameplay/rally/notebook/path')
local nb = Notebook("My Rally")
nb:setFname("/path/to/primary.notebook.json")
nb:save()

-- Load and use
nb:reload()
local codriver = nb:selectedCodriver()
local lang = nb:selectedCodriverLanguage()

-- Generate pacenotes from corners
nb:generatePacenotes(detectedCorners)
nb:autofillDistanceCalls()
nb:cacheCompiledPacenotes()
nb:save()

Notebook Path

Constructor

Public API (Key Methods)

Lifecycle

Codrivers

Pacenotes

Audio

Drawing

Mission Integration

Internals

File Format (v3)

Autofill Distance Calls

Pacenote Generation

Drawing Modes

Version Migration

How It Works

Usage Example

See Also

On this page

Notebook Path

Constructor

Public API (Key Methods)

Lifecycle

Codrivers

Pacenotes

Audio

Drawing

Mission Integration

Internals

File Format (v3)

Autofill Distance Calls

Pacenote Generation

Drawing Modes

Version Migration

How It Works

Usage Example

See Also

On this page