Crawl Save System

Reference for `gameplay_crawl_saveSystem`, which handles loading, saving, serialization, and caching of crawl trail data (trails, boundaries, paths, starting positions) as well as player score persist

Reference for gameplay_crawl_saveSystem, which handles loading, saving, serialization, and caching of crawl trail data (trails, boundaries, paths, starting positions) as well as player score persistence.

Overview

Provides a complete data layer for the crawl system. Manages JSON file I/O with lazy-loading cache, serialization/deserialization of all crawl data types, and a player save system for tracking best scores across freeroam and career modes.

Data Types

Type	File Pattern	Description
Trail	`*.trail.json`	Trail definition: references to path, boundary, starting position
Boundary	`*.boundary.json`	Zone boundary for crawl area
Path	`*.path.json`	Sequence of path nodes with positions, rotations, radii
Starting Position	`*.startingPosition.json`	Spawn point with transform and icon position

Core Exports

Loading / Getters

Function	Signature	Description
`getTrailById`	`(trailId)`	Load and cache a trail by file path
`getBoundaryById`	`(boundaryId)`	Load and cache a boundary
`getPathById`	`(pathId)`	Load and cache a path
`getStartingPositionById`	`(startingPositionId)`	Load and cache a starting position
`getAllTrails`	`()`	Get all trails for the current level
`getAllBoundaries`	`()`	Get all boundaries for the current level
`getAllPaths`	`()`	Get all paths for the current level
`getAllStartingPositions`	`()`	Get all starting positions
`getCurrentLevelCrawlPath`	`()`	Get the crawl data directory for the current level
`clearCache`	`(type)`	Clear cached data (specific type or all)

Saving

Function	Signature	Description
`saveTrail`	`(trail, filePath)`	Serialize and save a trail
`saveBoundary`	`(boundary, filePath)`	Serialize and save a boundary
`savePath`	`(path, filePath)`	Serialize and save a path
`saveStartingPosition`	`(startingPosition, filePath)`	Serialize and save a starting position
`loadCrawlData`	`(filename)`	Load a crawl data file (lists of trail references)
`saveCrawlData`	`(saveData, filepath)`	Save a crawl data file

Player Scores

Function	Signature	Description
`addNewPlayerScore`	`(trailId, time, penaltyPoints)`	Record a new score attempt
`getPlayerTrailStats`	`(trailId)`	Get best time, best points, attempts
`resetPlayerTrailScores`	`(trailId)`	Reset all scores for a trail
`getPlayerCrawlTrailById`	`(trailId)`	Get player trail data
`getPlayerCrawlTrailsById`	`()`	Get all player trail data
`ensurePlayerSaveDirectories`	`()`	Create save directories if missing
`isTrailFromMission`	`(trail)`	Check if trail is mission-sourced

File Structure

Crawl data lives under /levels/<levelName>/crawls/ with typed file extensions:

/levels/johnson_valley/crawls/
  ridgeway.trail.json
  ridgeway.boundary.json
  ridgeway.path.json
  ridgeway.startingPosition.json

Player scores are saved in:

Freeroam: settings/cloud/crawlTrails/
Career: <savePath>/career/crawlTrails/

How It Works

-- Load a trail and its dependencies
local trail = gameplay_crawl_saveSystem.getTrailById("/levels/jv/crawls/test.trail.json")
local boundary = gameplay_crawl_saveSystem.getBoundaryById(trail.boundaryId)
local path = gameplay_crawl_saveSystem.getPathById(trail.pathId)

-- Save a new trail
gameplay_crawl_saveSystem.saveTrail(trailData, "/levels/jv/crawls/new.trail.json")

-- Record a player score
gameplay_crawl_saveSystem.addNewPlayerScore(trailId, 142.5, 15)

-- Get player stats
local stats = gameplay_crawl_saveSystem.getPlayerTrailStats(trailId)
-- stats.bestTime, stats.bestPenaltyPoints, stats.attempts

Key Behaviors

Lazy loading with cache - Files are loaded on first access and cached by file path
Auto-metadata - Loaded items get _filePath, _fileName, _dir, _ext fields
Boundaries are deserialized using gameplay/sites/zone module with onDeserialized
Path nodes deserialize positions as vec3 and rotations as quat
Player scores track both best time and best penalty points independently
Career scores are saved via onSaveCurrentSaveSlot hook, freeroam scores save immediately
Score improvements are tracked: addNewPlayerScore returns isNewBestTime / isNewBestPenaltyPoints

File Discovery

Function	Signature	Description
`getAllTrailFiles`	`(levelPath)`	Returns all `.trail.json` files for a level
`getAllBoundaryFiles`	`(levelPath)`	Returns all `.boundary.json` files for a level
`getAllPathFiles`	`(levelPath)`	Returns all `.path.json` files for a level
`getAllStartingPositionFiles`	`(levelPath)`	Returns all `.startingPosition.json` files for a level

Utilities

Function	Signature	Description
`isTrailFromMission`	`(trail)` → bool	Checks if a trail originates from a mission
`cleanup`	`()`	Clears all cached data and player scores
`savePlayerCrawlTrailScoresForTrailById`	`(trailId)`	Saves player scores for a specific trail to disk

Hooks / Lifecycle

Function	Description
`onCareerActive`	Loads/unloads career-specific score data
`onSaveCurrentSaveSlot`	Persists career crawl scores into save slot
`M.addNewPlayerScore`	`(trailId, time, penaltyPoints)`
`M.cleanup`	`()`
`M.clearCache`	`(type)`
`M.ensurePlayerSaveDirectories`	`()`
`M.getAllBoundaries`	`()`
`M.getAllBoundaryFiles`	`(levelPath)`
`M.getAllPathFiles`	`(levelPath)`
`M.getAllPaths`	`()`
`M.getAllStartingPositionFiles`	`(levelPath)`
`M.getAllStartingPositions`	`()`
`M.getAllTrailFiles`	`(levelPath)`
`M.getAllTrails`	`()`
`M.getBoundaryById`	`(boundaryId)`
`M.getCurrentLevelCrawlPath`	`()`
`M.getPathById`	`(pathId)`
`M.getPlayerCrawlTrailById`	`(trailId)`
`M.getPlayerCrawlTrailsById`	`()`
`M.getPlayerTrailStats`	`(trailId)`
`M.getStartingPositionById`	`(startingPositionId, trail)`
`M.getTrailById`	`(trailId)`
`M.isTrailFromMission`	`(trail)`
`M.loadCrawlData`	`(filename)`
`M.onCareerActive`	`()`
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`
`M.resetPlayerTrailScores`	`(trailId)`
`M.saveBoundary`	`(boundary, filePath)`
`M.saveCrawlData`	`(saveData, filepath)`
`M.savePath`	`(path, filePath)`
`M.savePlayerCrawlTrailScoresForTrailById`	`(trailId)`
`M.saveStartingPosition`	`(startingPosition, filePath)`
`M.saveTrail`	`(trail, filePath)`

Overview

Data Types

Type	File Pattern	Description
Trail	`*.trail.json`	Trail definition: references to path, boundary, starting position
Boundary	`*.boundary.json`	Zone boundary for crawl area
Path	`*.path.json`	Sequence of path nodes with positions, rotations, radii
Starting Position	`*.startingPosition.json`	Spawn point with transform and icon position

Core Exports

Loading / Getters

Function	Signature	Description
`getTrailById`	`(trailId)`	Load and cache a trail by file path
`getBoundaryById`	`(boundaryId)`	Load and cache a boundary
`getPathById`	`(pathId)`	Load and cache a path
`getStartingPositionById`	`(startingPositionId)`	Load and cache a starting position
`getAllTrails`	`()`	Get all trails for the current level
`getAllBoundaries`	`()`	Get all boundaries for the current level
`getAllPaths`	`()`	Get all paths for the current level
`getAllStartingPositions`	`()`	Get all starting positions
`getCurrentLevelCrawlPath`	`()`	Get the crawl data directory for the current level
`clearCache`	`(type)`	Clear cached data (specific type or all)

Saving

Function	Signature	Description
`saveTrail`	`(trail, filePath)`	Serialize and save a trail
`saveBoundary`	`(boundary, filePath)`	Serialize and save a boundary
`savePath`	`(path, filePath)`	Serialize and save a path
`saveStartingPosition`	`(startingPosition, filePath)`	Serialize and save a starting position
`loadCrawlData`	`(filename)`	Load a crawl data file (lists of trail references)
`saveCrawlData`	`(saveData, filepath)`	Save a crawl data file

Player Scores

Function	Signature	Description
`addNewPlayerScore`	`(trailId, time, penaltyPoints)`	Record a new score attempt
`getPlayerTrailStats`	`(trailId)`	Get best time, best points, attempts
`resetPlayerTrailScores`	`(trailId)`	Reset all scores for a trail
`getPlayerCrawlTrailById`	`(trailId)`	Get player trail data
`getPlayerCrawlTrailsById`	`()`	Get all player trail data
`ensurePlayerSaveDirectories`	`()`	Create save directories if missing
`isTrailFromMission`	`(trail)`	Check if trail is mission-sourced

File Structure

Crawl data lives under /levels/<levelName>/crawls/ with typed file extensions:

/levels/johnson_valley/crawls/
  ridgeway.trail.json
  ridgeway.boundary.json
  ridgeway.path.json
  ridgeway.startingPosition.json

Player scores are saved in:

Freeroam: settings/cloud/crawlTrails/
Career: <savePath>/career/crawlTrails/

How It Works

-- Load a trail and its dependencies
local trail = gameplay_crawl_saveSystem.getTrailById("/levels/jv/crawls/test.trail.json")
local boundary = gameplay_crawl_saveSystem.getBoundaryById(trail.boundaryId)
local path = gameplay_crawl_saveSystem.getPathById(trail.pathId)

-- Save a new trail
gameplay_crawl_saveSystem.saveTrail(trailData, "/levels/jv/crawls/new.trail.json")

-- Record a player score
gameplay_crawl_saveSystem.addNewPlayerScore(trailId, 142.5, 15)

-- Get player stats
local stats = gameplay_crawl_saveSystem.getPlayerTrailStats(trailId)
-- stats.bestTime, stats.bestPenaltyPoints, stats.attempts

Key Behaviors

Lazy loading with cache - Files are loaded on first access and cached by file path
Auto-metadata - Loaded items get _filePath, _fileName, _dir, _ext fields
Boundaries are deserialized using gameplay/sites/zone module with onDeserialized
Path nodes deserialize positions as vec3 and rotations as quat
Player scores track both best time and best penalty points independently
Career scores are saved via onSaveCurrentSaveSlot hook, freeroam scores save immediately
Score improvements are tracked: addNewPlayerScore returns isNewBestTime / isNewBestPenaltyPoints

File Discovery

Function	Signature	Description
`getAllTrailFiles`	`(levelPath)`	Returns all `.trail.json` files for a level
`getAllBoundaryFiles`	`(levelPath)`	Returns all `.boundary.json` files for a level
`getAllPathFiles`	`(levelPath)`	Returns all `.path.json` files for a level
`getAllStartingPositionFiles`	`(levelPath)`	Returns all `.startingPosition.json` files for a level

Utilities

Function	Signature	Description
`isTrailFromMission`	`(trail)` → bool	Checks if a trail originates from a mission
`cleanup`	`()`	Clears all cached data and player scores
`savePlayerCrawlTrailScoresForTrailById`	`(trailId)`	Saves player scores for a specific trail to disk

Hooks / Lifecycle

Function	Description
`onCareerActive`	Loads/unloads career-specific score data
`onSaveCurrentSaveSlot`	Persists career crawl scores into save slot
`M.addNewPlayerScore`	`(trailId, time, penaltyPoints)`
`M.cleanup`	`()`
`M.clearCache`	`(type)`
`M.ensurePlayerSaveDirectories`	`()`
`M.getAllBoundaries`	`()`
`M.getAllBoundaryFiles`	`(levelPath)`
`M.getAllPathFiles`	`(levelPath)`
`M.getAllPaths`	`()`
`M.getAllStartingPositionFiles`	`(levelPath)`
`M.getAllStartingPositions`	`()`
`M.getAllTrailFiles`	`(levelPath)`
`M.getAllTrails`	`()`
`M.getBoundaryById`	`(boundaryId)`
`M.getCurrentLevelCrawlPath`	`()`
`M.getPathById`	`(pathId)`
`M.getPlayerCrawlTrailById`	`(trailId)`
`M.getPlayerCrawlTrailsById`	`()`
`M.getPlayerTrailStats`	`(trailId)`
`M.getStartingPositionById`	`(startingPositionId, trail)`
`M.getTrailById`	`(trailId)`
`M.isTrailFromMission`	`(trail)`
`M.loadCrawlData`	`(filename)`
`M.onCareerActive`	`()`
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`
`M.resetPlayerTrailScores`	`(trailId)`
`M.saveBoundary`	`(boundary, filePath)`
`M.saveCrawlData`	`(saveData, filepath)`
`M.savePath`	`(path, filePath)`
`M.savePlayerCrawlTrailScoresForTrailById`	`(trailId)`
`M.saveStartingPosition`	`(startingPosition, filePath)`
`M.saveTrail`	`(trail, filePath)`

Crawl Save System

Overview

Data Types

Core Exports

Loading / Getters

Saving

Player Scores

File Structure

How It Works

Key Behaviors

File Discovery

Utilities

Hooks / Lifecycle

See Also

On this page

Crawl Save System

Overview

Data Types

Core Exports

Loading / Getters

Saving

Player Scores

File Structure

How It Works

Key Behaviors

File Discovery

Utilities

Hooks / Lifecycle

See Also

On this page