Gameplay City

Loads and queries city-level site data (zones, parking spots) with priority-based zone lookups. Used for level metadata like traffic rules, vehicle groups, and delivery routing.

Public API

| Function | Signature | Returns | Description | |------ | M.dependencies | table | {'gameplay_sites_sitesManager'} |----| | M.onClientEndMission | onClientEndMission handler |-----------|---------|-------------| | M.loadSites | (file?) | nil | Loads sites from file; defaults to level's city.sites.json | | M.getSites | () | sites\|nil | Returns loaded sites object | | M.reset | () | nil | Clears loaded sites | | M.getZonesByPrioForPosition | (pos) | table, number | Returns zones at position grouped by priority, and highest priority | | M.getHighestPrioZone | (pos) | zone\|nil | Returns the single highest-priority zone containing position | | M.getMergedFieldsFromZones | (pos, fieldName) | table | Returns unique custom field values from highest-priority zones | | M.getRandomParkingSpots | (minDist?, startName?) | nameA, nameB, zoneA, zoneB | Returns random start/destination parking spots with minimum distance |

Dependencies

• gameplay_sites_sitesManager

Zone Priority System

Zones have an optional priority custom field. When multiple zones overlap at a position:

• getZonesByPrioForPosition() returns all zones grouped by priority value
• getHighestPrioZone() returns only the zone with the highest priority
• getMergedFieldsFromZones() extracts custom fields from highest-priority zones

Custom fields support up to 5 suffixes per zone: fieldName, fieldName1, fieldName2, etc.

How It Works

1. Loading: On onClientStartMission, loads city.sites.json from level directory
2. Zone Queries: Uses sites:getZonesForPosition() or sites:zonesForPositionIterator() for spatial lookups
3. Parking Spots: getRandomParkingSpots() shuffles all named spots, finds two with distance ≥ minDist (default 300), returns their zone names sorted by priority

Usage Examples

-- Load city sites
gameplay_city.loadSites()

-- Get highest priority zone at player position
local zone = gameplay_city.getHighestPrioZone(playerPos)

-- Get vehicle group fields
local groups = gameplay_city.getMergedFieldsFromZones(pos, "vehicleGroup")

-- Get random delivery endpoints
local startSpot, endSpot, startZone, endZone = gameplay_city.getRandomParkingSpots(500)

Notes

• Sites cached after first load; only one sites file active at a time
• Default file path: <levelDir>/city.sites.json
• Requires at least 2 parking spots for getRandomParkingSpots()
• Zone priority defaults to 0 if not specified
• Used by traffic, delivery, and other systems for spatial context

Module Variables

See Also

• Gameplay Achievement - Related reference
• discover - Discover / Experience System - Related reference
• Force Field - Related reference
• Gameplay Systems Guide - Guide