Driver Profile and Persistence

Driver Profile and Persistence

TaxiDriver stores user data outside the mod archive under:

%LOCALAPPDATA%\BeamNG\BeamNG.drive\current\settings\TaxiDriver\

General settings, portable difficulty, profile, progress, per-vehicle history, restorable shift history, fleet statistics, and LAN pairing identity are separate so one corrupt document does not reset unrelated data.

settings.json

{
  "schemaVersion": 1,
  "modVersion": "3.2.0-beta",
  "language": "en",
  "rememberLanguage": false,
  "difficulty": "standard",
  "uiScalePercent": 100,
  "appVolume": 0.65,
  "unitSystem": "metric",
  "timeFormat": "12h",
  "dynamicZoomIntensity": 100,
  "economyMultiplier": 1,
  "deliveryOrderSharePercent": 50,
  "silentMode": false,
  "showRouteGuidance": true,
  "realisticMode": false,
  "randomEventsEnabled": false,
  "unlimitedRouteDistance": false,
  "aiDebugLogging": false,
  "aiDriver": {
    "preset": "balanced",
    "obeySpeedLimits": true,
    "obeyTrafficSignals": true,
    "allowOvertaking": true,
    "laneChangeClearancePercent": 100,
    "allowOncomingRecovery": true,
    "allowReverseRecovery": true,
    "recoveryMaxAttempts": 3,
    "finalApproachSpeedKmh": 12,
    "aggressionPercent": 30,
    "followingTimeGap": 2.2,
    "brakingDeceleration": 2.8,
    "stuckDelaySeconds": 15
  },
  "fleet": {
    "enabled": true,
    "aiPreset": "standard",
    "ownerSharePercent": 35,
    "hiringFee": 75,
    "wagePerTenMinutes": 12,
    "maxDrivers": 6,
    "worldLabelDistance": 400,
    "passengerJobs": true,
    "deliveryJobs": true
  }
}

uiScalePercent is rounded to 10% steps and clamped to 80–180%. Version 2.24.0 migrates a legacy fontBoost value automatically; the previous default 2 maps to 100%. Version 3.1.1 RC migrates the former obeyTrafficRules AI object to a custom preset and copies the value into both independent rule switches. appVolume is clamped to 0–1. Unsupported languages and difficulties return to defaults. Connected phone is deliberately excluded and always starts disabled.

difficulty.json

This portable file contains the Custom difficulty slider values and the seven individual penalty switches. It can be shared between players without exposing profile, wallet, language, or LAN pairing data. Invalid fields are clamped to the ranges defined in config.lua.

profile.json

{
  "schemaVersion": 1,
  "modVersion": "3.2.0-beta",
  "fullName": "John Doe",
  "birthDate": "",
  "avatar": "🙂"
}

• Names are trimmed, internal repeated spaces are collapsed, and length is limited to 160 bytes.
• Birth date uses YYYY-MM-DD, must represent a valid calendar date, and accepts years from 1900 through the current year.
• Avatar must be one of the 32 values defined in identity.lua.

Age is calculated by the UI and is not persisted.

progress.json

The progress document contains:

• wallet balance;
• current rating;
• accumulated rating total and count;
• completed ride count;
• monotonically increasing sequence ID;
• passenger reviews;
• rating history;
• balance history.

Representative structure:

{
  "schemaVersion": 1,
  "modVersion": "3.2.0-beta",
  "balance": 24.75,
  "rating": 4.82,
  "ratingTotal": 48.2,
  "ratingCount": 10,
  "completedRides": 10,
  "aiRideCount": 3,
  "sequence": 10,
  "reviews": [
    {
      "id": 10,
      "passengerName": "Amelia Howard",
      "emoji": "😍",
      "quality": 94,
      "fare": 12.85,
      "orderRating": 5.0,
      "rating": 4.82,
      "usedAutopilot": true,
      "timestamp": 1784040000,
      "outcome": "completed"
    }
  ],
  "ratingHistory": [{"index": 10, "value": 4.82, "timestamp": 1784040000}],
  "balanceHistory": [{"index": 10, "value": 24.75, "timestamp": 1784040000}]
}

progress.json also stores lastShift, including timestamps, ride count, gross income, fuel cost, penalty loss, net income, rating total, and average rating.

Valid outcomes include passenger completion/exit/abandonment and delivery completion/abandonment.

Reviews and history are not given a fixed retention limit. The UI measures the actual review panel and the rendered regular/AI-assisted row heights, then chooses the largest page size that fits without overlapping the sticky pager. It recalculates after viewport, interface-scale, locale, tab, or data changes.

vehicles.json

The vehicle journal is keyed by BeamNG model and configuration identity. A record is persisted only after that vehicle completes at least one ride. Each record can contain:

• selector name and preview path;
• total odometer distance tracked by TaxiDriver;
• completed, passenger, and cargo ride counts;
• total and average income;
• rating total/count and average rating;
• penalty and cargo-damage losses;
• consumed fuel/energy and fuel cost;
• work-route distance and profit per kilometre.

The currently selected vehicle is available to the start screen even before it qualifies for history. Vehicle switching and level reloads refresh the card immediately. Implausible reset/teleport jumps are rejected from odometer accumulation.

shiftshistory.json

Shift history is intentionally separate from progress.json. It can be discarded without losing wallet, rating, reviews or vehicle lifetime statistics.

Each retained entry contains:

• a monotonically increasing shift ID and start/end/save timestamps;
• BeamNG model key, configuration key/path, selector name and preview;
• primary energy type plus fuel and/or electric percentages;
• rides, AI rides, gross income, fuel cost, penalties, net income and average rating.

Only shifts with at least one completed ride are written. At most 50 entries are retained. After BeamNG's vehicle registry is ready, entries whose model/configuration no longer exists are removed instead of offering an unrestorable shift.

sequenceDiagram
  participant Shift as shiftTracker
  participant History as shiftHistory.lua
  participant Vehicle as BeamNG vehicle registry
  participant Storage as shiftshistory.json

  Shift->>History: begin(vehicle identity, energy, totals)
  loop every 60 seconds while active
    History->>Vehicle: capture compatible energy storage
    History->>Storage: sanitized snapshot (only after first ride)
  end
  Shift->>History: finish or switch vehicle
  History->>Storage: final snapshot
  Note over History,Storage: game shutdown is not required to use a finish button
  History->>Vehicle: validate installed model/configuration
  History->>Storage: remove unavailable or zero-ride entries
  History->>Vehicle: resume selected configuration
  Vehicle-->>History: replacement VM settled
  History->>Vehicle: restore fuel/charge percentages

Loading

The restore flow uses the same guarded vehicle-replacement lifecycle as normal selector changes. Energy is applied only after the replacement vehicle VM is available; stale callbacks from the previous vehicle are ignored.

fleet.json

Fleet statistics are separate from personal progress and active workers. The file stores aggregate totals plus per-vehicle totals for rides, passenger/cargo split, distance, gross and owner revenue, wages, and hiring fees. Statistics are sanitized on load and written after a short dirty-state debounce and at session shutdown.

Active employees are intentionally not restored across levels or game launches. They own live BeamNG vehicle IDs and are released when the session ends; only their completed economic history persists. See Fleet Operations.

Validation and recovery

Every file has schemaVersion = 1. On extension load:

1. the file is read inside pcall;
2. schema and fields are sanitized;
3. unsupported schema or invalid root data falls back to defaults;
4. a canonical sanitized document is immediately written back.

If progress.json does not exist, the extension can import balance/rating values from BeamNG extension serialization once, then writes the new progress file.

Write points

• Settings and portable difficulty: automatically after a UI change debounce.
• Profile: when the profile identity page is saved.
• Progress: completed ride, passenger exit, driver abandonment, shift completion, fuel purchase, mission end, and extension unload.
• Vehicle history: travelled distance debounce, completed ride, mission end, and extension unload.
• Shift history: first completed ride, 60-second active snapshots, vehicle/shift transition, mission end, and extension unload.
• Fleet statistics: completed fleet job, hiring/wage accounting after a five-second debounce, session end, and extension unload.

Backup and reset

To back up progress, copy the complete settings/TaxiDriver directory while the game is not writing it.

To reset only one category, remove the corresponding JSON file. The next extension load recreates that file with defaults and leaves the other documents untouched.

lan.json

lan.json stores the stable random External Web UI token and last selected private IPv4 address. It does not store an enabled flag. Connected phone remains off after every mod/UI App start. Delete this file to generate a new pairing token.