Waypoints

The Waypoints plugin provides server-authoritative world navigation with a VMF-scaled minimap, hosted F1 map, compact compass and a through-wall marker. Saved locations, dynamic nearest-entity destinations and system destinations all use the same selection path.

Player commands

/waypoint <location>
/waypoint goto <location>
/waypoint clear
/waypoint end
/waypoint stop
/waypoints list

/waypoints list prints every currently available public destination, its category and the matching /waypoint command to the player's console. The former /waypoints Derma menu remains removed.

The F1 Map interface is searchable and grouped by category. It includes saved map locations, dynamic Nearest destinations and locations registered by another system. It deliberately excludes the legacy /place coordinate table from ordinary player navigation.

VMF map projection

The HUD minimap and F1 Map use the same exported map artwork and reversible Source-world transform. The rp_evocity_v4b1_fl2 definition currently uses:

HUD image: rp_evocity_v4b1_fl2_gmod.png
Image size: 3896 x 4096
World X: -16368 to 12944
World Y: -15446 to 15376
Y axis: image top is maximum world Y

World positions are converted into normalized texture coordinates:

u = (worldX - minX) / (maxX - minX)
v = (maxY - worldY) / (maxY - minY)

WorldToMapUV and MapUVToWorld expose both directions of the transform. The HUD minimap, F1 player marker, active waypoint marker and positioned map pins therefore share one coordinate system rather than separate manually tuned percentages.

Map material cache

The client downloads the 3896×4096 in-game derivative from the configured beta map path, validates its PNG signature and stores it under:

data/cityrp/waypoints/maps/<map>_<version>.png

The cached file is loaded as the native HUD material. The hosted F1 page uses the same optimized 3896×4096 derivative and exact canvas ratio as the HUD. This avoids decoding a roughly 1.1 GB RGBA source texture, eliminates letterbox drift between pins and artwork, and cuts the map download from roughly 1.5 MB to 125 KB. A version change in the shared map definition produces a new HUD cache filename. The F1 page uses a versioned service-worker cache for its map, scripts, styles and pin images.

HUD minimap

The GTA-inspired minimap uses the same background and outline colours as the TEAM/ALL radio panel. Its default width matches the 294-pixel Limelight citizen HUD panel.

The map remains centred on the player and rotates to keep the navigation heading at the top. On foot, the minimap, compass, full-map marker and F1 player arrow use camera yaw. While seated, they use the player model's vehicle-aligned render yaw, so free-looking cannot skew navigation away from the direction of travel. The redundant north pointer is hidden because the integrated compass provides cardinal orientation. The minimap shows the active destination as an edge-clamped marker when it is outside the visible crop, without repeating its name or distance under the map. The north-up F1 map uses the same white four-point player arrow and rotates it to the current model-facing heading.

The minimap is enabled by default and remains fixed at the top right. Hold C and open HUD Options → Toggle Minimap to toggle it, choose Default Size or Small Size, and independently toggle its compass section. The former /minimap command and alternate screen anchors have been removed.

The −, reset and + controls in the minimap's upper-right corner use the hosted F1 map styling at a smaller HUD scale and change its crop zoom. They accept mouse input while the player holds C. Visibility, size, compass and zoom preferences are archived client-side. Areas beyond the map image are filled with #1a1a1a.

When a waypoint is active, the minimap draws the server-calculated route along the exported road surfaces. The #0D47A1 road stroke uses rounded corners and caps. Its #546E7A off-road sections identify the connection from an off-road player or destination back to the nearest recognized road. The destination remains edge-clamped when it is outside the visible crop.

Hosted F1 city map

Pressing M opens the F1 menu directly on the Map tab. The console command cityrp_open_map exposes the same behaviour for custom binds.

The F1 panel hosts the beta service-map interface so its category controls, location cards and full pin artwork remain identical to the browser map. It supports:

• mouse-wheel zoom;
• left-drag panning;
• a reset control;
• active-navigation state; and
• interactive server-authoritative location pins.

Clicking a pin selects it and centres its anchor in the current map view. The location list remains searchable and filterable by the category controls at the top. Clicking either a row or its Set Waypoint button focuses the same pin before selecting the destination.

Static locations use their saved world coordinates. Registered system destinations use their resolver coordinates. Dynamic destinations are refreshed from the current matching entity's WorldSpaceCenter().

The server sends those locations to the client through CityRP.Waypoints.MapData. The client converts Source world positions through WorldToMapUV and injects a JSON payload into the already-loaded DHTML page with CityRPMapSetLocations. This data exists only in that player's in-memory page:

• the game server does not POST coordinates to the website;
• the website does not receive database credentials;
• no public JSON file is modified on server startup; and
• a fresh server response replaces stale browser-map positions.

This is preferable for the in-game F1 map because live and nearest resolvers can change. !waypointexport remains the controlled workflow for updating the standalone public map.

Nearest map category

The hosted F1 map includes a Nearest category. Its entries are list-only:

• they are visible in the category and location list;
• they do not create map pins;
• clicking the entire location row sets the waypoint; and
• the existing Set Waypoint button performs the same action.

Nearest destinations resolve to the closest currently valid entity each time they are selected:

Identifier	Destination
locker	Government Locker
weed	Drug Dealer
meth	Meth Dealer
coal	Coal Mine
metal	Metal Mine
tree	Pine Tree
bin	Rubbish Bin
trash	Trash Collector
wood	Wood Chopper
rocks	Construction Worker
terminal	ID Terminal
vending_machine	Vending Machine
tesla_supercharger	Tesla Supercharger
fuel_station	Fuel Station
phonebooth	Phonebooth

Persistent map locations

Roleplay Assistants and higher staff can save locations to the current map while looking at the required position:

!waypointset <name> [hidden|visible]
!waypointsetcategory <location> <category>
!waypointdelete <name>

New locations begin in General.

All privileged functions use documented acommands:

Example	Description
!waypointset "Industrial Road" visible	Save or update the aimed position
!waypointcategory add "Fuel Stations" red diamond	Create, edit, list or remove categories
!waypointsetcategory "Inner City BP" "Fuel Stations"	Move a saved location
!waypointhide "Staff Garage"	Hide a saved pin
!waypointshow "Staff Garage"	Restore a saved pin
!waypointdelete "Old Location"	Delete a saved location
!waypointplayer Vadar "Inner City BP"	Assign or clear another player's route
!waypointexport	Print the current map JSON
!waypointdebug roads	Inspect the road graph and route

The same examples and descriptions appear in the F1 Commands page for authorized staff.

Locations are stored under:

data/cityrp/plugins/waypoints/<map>.json

Repository-managed configurations may be placed under:

gamemode/core/plugins/waypoints/maps/<map>.json

The server imports a changed packaged configuration once and records its checksum under data/cityrp/plugins/waypoints/imports/. Later in-game edits are therefore not overwritten on every restart.

Staff can print the complete current map configuration to their client console:

!waypointexport

The export is the correct source for a reviewed public-map update. An automatic server-to-website upload would require an authenticated write endpoint, replay protection, map/version validation and deployment rollback. Runtime DHTML injection avoids that operational and security surface for the in-game map.

Hidden locations

A saved location can remain addressable without appearing in the F1 location list:

!waypointhide <name>
!waypointshow <name>
!waypointset <name> hidden

Hidden locations remain usable through direct selection, staff assignment and system integrations.

Nearest entries are different from hidden saved points: they remain visible in the F1 list but are marked as list-only so the map does not draw a pin.

Categories

!waypointcategory add <name> [colour] [shape]
!waypointcategory set <name> [colour] [shape]
!waypointcategory remove <name>
!waypointcategory list

create aliases add, edit aliases set, and delete aliases remove. Removing a category moves its saved locations to General.

Supported colours are blue, green, orange, red, yellow, purple and white. Supported shapes are diamond, circle, square and triangle.

Multi-word category names use an underscore identifier, such as City Services becoming city_services.

Buildings and road routing

The map PNG is visual artwork only. Buildings, water and terrain may change without changing navigation. Road routing uses the packaged rp_evocity_v4b1_fl2_roads.json, which contains world-coordinate road polygons and holes exported from the VMF.

On server startup, the plugin samples that geometry into a connected 256-unit road grid. A waypoint projects the player and destination onto their nearest road nodes, runs A* with diagonal corner protection, and simplifies the result only where the straight segment remains within the exported road surface. The server sends the resulting world-coordinate route with the waypoint. It recalculates only when the player moves more than three grid cells from the active route.

The route geometry is independent from the PNG and therefore cannot mistake a building colour for a road. The current graph is bidirectional because the source data describes surfaces rather than lane direction. One-way support would require directed lane or edge metadata in a future export.

Roleplay Assistants and higher staff can inspect the routing system with:

!waypointdebug roads
!waypointdebug route
!waypointdebug status
!waypointdebug off

The roads mode draws every recognized road-grid node in green over the base map, draws active route points in yellow and leaves the calculated path in its normal on-road and off-road colours. The minimap also displays the road-node and route-point counts. route and status print the graph load state, source path and active route coordinates to the console. This distinguishes a missing graph from a route-calculation or HUD-rendering problem.

Staff directions

!waypointplayer <player> <location>
!waypointplayer <player> clear
!waypointplayer <player> end
!waypointplayer <player>

The player argument accepts a partial or full name, server UserID or legacy SteamID through CityRP's normal lookup. Without a destination, the waypoint uses the staff member's aimed position.

Staff assignment may resolve the existing /place and /warp tables for compatibility. Those legacy coordinates are not exposed in the ordinary player menu.

Server API

local waypoints = cityrp.plugin.get("waypoints")

waypoints:SetWaypoint(
	ply,
	"Delivery",
	Vector(100, 200, 300),
	260,
	"example",
	false,
	"orange",
	"triangle",
	"deliveries"
)

waypoints:ClearWaypoint(ply, "example")

waypoints:RegisterDestination(
	"example",
	"Example Destination",
	Vector(100, 200, 300),
	260,
	"green",
	"circle",
	"services"
)

Source identifiers allow systems to clear only their own navigation without removing a staff or unrelated system waypoint.

Car Boosting

When Waypoints is loaded, Car Boosting replaces another active destination with a silent Chop Shop waypoint when delivery begins. It clears when delivery completes, fails or the player enters the destination radius.

Without Waypoints, the Boosting objective HUD retains its own delivery bearing and distance.

Runtime checks

1. Clear the map material cache and confirm the PNG downloads and renders in both HUD and F1.
2. Verify both minimap sizes, visibility and compass toggles from the C menu.
3. Hold C and verify + and − change the minimap crop zoom.
4. Walk and drive between known landmarks and verify world movement matches the minimap.
5. Set distant waypoints and verify the blue route follows roads and reroutes after leaving them.
6. Rotate on foot and in a vehicle, then look independently, and verify the expected heading remains correct.
7. Press M and confirm F1 opens directly on the hosted Map panel.
8. Verify F1 zoom, pan, reset, player position and active navigation marker.
9. Compare saved pins against their corresponding doors, properties and service entities.
10. Confirm Nearest entries draw no pins and both row/button actions resolve the closest live entity.
11. Test saved categories, hidden points, staff assignment and automatic clearing inside the arrival radius.