Freeroam Level Stats

Tracks and persists usage statistics for levels and spawn points. Records spawn counts and timestamps, provides sorted top-level and top-spawn-point queries.

Public API

Storage Format

File: /settings/cloud/uiStats.json

{
  "levels": {
    "west_coast_usa": {
      "count": 15,
      "lastUsed": "2024-01-15T10:30:00Z",
      "spawnPoints": {
        "spawns_industrial": {
          "spawnPointName": "spawns_industrial",
          "count": 8,
          "lastUsed": "2024-01-15T10:30:00Z"
        }
      }
    }
  },
  "vehicles": {}
}

How It Works

1. recordLevelSpawn() increments counters and updates ISO8601 timestamps for level and spawn point
2. Default spawn points (no name) stored as "__default__"
3. getTopLevels() sorts by count (descending) but promotes the most recently used level to first position
4. getTopSpawnPoints() follows the same sorting strategy per level
5. Stats cached in memory after first read

Usage Examples

-- Record a level spawn
freeroam_levelStats.recordLevelSpawn("west_coast_usa", "spawns_industrial")

-- Get most-used levels
local topLevels = freeroam_levelStats.getTopLevels()
-- Returns: {{levelName="west_coast_usa", count=15, lastUsed="..."}, ...}

-- Get spawn points for a level
local spawns = freeroam_levelStats.getTopSpawnPoints("west_coast_usa")

Notes

• Stats file is in the cloud save directory for cross-device sync
• Timestamps in ISO8601 UTC format
• The vehicles table exists in the schema but is not currently populated
• Sorting prioritizes the most recently used entry at position 1, then sorts remainder by count

See Also

• Freeroam Big Map Markers - Related reference
• Freeroam Big Map Mode - Related reference
• Freeroam Big Map POI Provider - Related reference
• Freeroam Guide - Guide