Why have we gone to an extraordinary effort modelling the wind for cycling?

1. An extension has two files

A UI-only extension needs no calculation. Its Lua file can contain one comment while the UI binds directly to an existing stream.

Custom streams

Define point-by-point calculations in meta.json using customStreams. They run in the browser after result streams load and appear in chart selectors and the Data Panel. Their Lua file can contain a single comment.

This example calculates estimated power minus recorded power. Positive values mean overestimation; the average is signed bias. Missing inputs produce gaps. Use local stream names in this extension's UI bindings. Set a parameter's refreshRequired to false when it is used only for local calculations or presentation.

{
  "schemaVersion": 4,
  "name": "Power Estimate Error",
  "description": "Compare estimated power with recorded power at each route point.",
  "modes": {
    "analysis": true,
    "prediction": false
  },
  "parameters": [],
  "customStreams": [
    {
      "key": "estimateError",
      "label": "Power estimate error",
      "description": "Estimated minus recorded power. Positive values indicate overestimation.",
      "unitGroup": "power",
      "unit": "w",
      "precision": 0,
      "inputs": {
        "estimated": {
          "stream": "powerWattsEstimated"
        },
        "recorded": {
          "stream": "powerWatts"
        }
      },
      "calculate": {
        "type": "expression",
        "expression": "estimated - recorded"
      },
      "metrics": [
        "average",
        "min",
        "max"
      ]
    }
  ],
  "ui": {
    "components": []
  }
}

Expressions support arithmetic, comparisons, conditionals and min, max, abs and clamp. Inputs and output units are canonical (power uses w). Custom streams can depend on other custom streams in the same extension, but cannot form a cycle or alter the simulation.

2. A small working example

This publishes a Yes/No climbing status using an adjustable threshold.

export("guideClimbing", "status", "", "Climbing")

local threshold = tonumber(extensionParameters.climbThreshold) or 0.03
local validSlope = type(slope) == "number"
    and slope == slope
    and slope > -math.huge
    and slope < math.huge

guideClimbing = validSlope and slope >= threshold

{
  "schemaVersion": 3,
  "name": "Climbing status",
  "description": "Shows when the route is climbing.",
  "modes": {
    "analysis": true,
    "prediction": true
  },
  "parameters": [{
    "key": "climbThreshold",
    "label": "Climb threshold",
    "description": "Decimal gradient; 0.03 means 3%.",
    "type": "number",
    "defaultValue": 0.03,
    "min": 0, "max": 0.3, "step": 0.005,
    "unit": "", "unitGroup": "",
    "refreshRequired": true,
    "options": []
  }],
  "ui": { "components": [] }
}

modes.analysis and modes.prediction state where the extension is relevant. Set either flag to false to keep its Lua and UI out of that mode. Missing or non-boolean flags default to true, so older extensions remain available in both modes.

Important: slope is decimal rise/run. 0.05 means 5%; 5 means 500%.

3. Add presentation without JavaScript

ui.components describes presentation using route streams, parameters or genuine Lua exports.

• Use an existing stream directly when it already contains the value.
• For markers, content.label is visible on the map and timeline; content.description appears in details.
• Map lines accept a coordinate-pair stream through source.geometry, or separate numeric source.latitude and source.longitude bindings.
• Chart and Data Panel items are suggestions which the user chooses to apply. They do not silently replace formatting.
• Bindings use canonical stored values. A unit label never changes a number's scale.

{
  "id": "brakingLine",
  "type": "mapLine",
  "variant": "polyline",
  "source": {
    "mode": "binding",
    "geometry": { "source": "stream", "key": "latlng_offset" }
  },
  "appearance": {
    "color": "#22c55e",
    "colorBy": { "source": "stream", "key": "brakingSeverity" },
    "colorScale": [
      { "value": 0, "color": "#22c55e" },
      { "value": 0.5, "color": "#f59e0b" },
      { "value": 1, "color": "#7f1d1d" }
    ],
    "opacity": 0.9,
    "weight": 5,
    "lineStyle": "solid"
  },
  "placements": [{ "surface": "map", "mode": "line" }],
  "limits": { "maxPoints": 10000 }
}

4. Understand when Lua runs

The combined extension code runs before each route point is solved, often thousands of times per pass.

An extension may calculate its own theoretical or estimated current-point value from the available inputs. Keep the calculation lightweight and bounded, explain important assumptions, and do not present the estimate as the main solver's actual current-point result.

routeContext provides bounded, static terrain and major-corner summaries calculated before modelling. Use routeIdx, currentTerrainSegmentNumber, nextCornerNumber and distanceToNextCornerM for efficient per-point access. Route indexes are zero-based, context arrays are one-based Lua arrays, and each endIdxExclusive is the first point outside its range. A corner remains next at its apex and advances on the following point; a corner number of 0 and distance of -1 mean none remains.

Each analysis or prediction starts clean. Globals persist between points during that pass; top-level local values are recreated every call. Prefix persistent globals because active extensions share the container.