Rally JSONL Utilities

Utility module for reading JSON Lines (JSONL) files - line-delimited JSON format used for recce recordings (driveline, cuts, transcripts).

Public API

How It Works

parseJsonlFile(fname, processLine, rallyUtil)

1. Checks file existence via FS:fileExists
2. Reads entire file into memory
3. Splits into lines, trims whitespace (using rallyUtil.trimString)
4. Skips empty lines and // comments
5. Decodes each line as JSON via jsonDecode
6. Optionally transforms via processLine(obj) callback
7. Returns array of parsed objects

readJsonlLines(fname, callback)

Simpler alternative using io.lines iterator. Calls callback(obj) for each decoded line. No comment handling or trimming.

local jsonlUtils = require('gameplay/rally/util/jsonlUtils')
local rallyUtil = require('gameplay/rally/util')

-- Parse a driveline recording
local points, err = jsonlUtils.parseJsonlFile(
  '/path/to/driveline.json',
  function(obj)
    obj.pos = vec3(obj.pos)
    return obj
  end,
  rallyUtil
)

-- Simple read
jsonlUtils.readJsonlLines('/path/to/data.jsonl', function(obj)
  print(obj.ts, obj.pos.x)
end)

Notes

• JSONL format: one JSON object per line, no wrapping array
• Comment lines starting with // are supported by parseJsonlFile only
• readFileToMemory uses raw io.open, not BeamNG's FS API
• parseJsonlFile uses FS:fileExists for the existence check

See Also

• Rally Utility Colors - Related reference
• Rally Utility Normalizer - Related reference
• Gameplay Systems Guide - Guide