# z-eus/zeus_custom_waypoint architecture

> Architecture diagram of the GitHub repository z-eus/zeus_custom_waypoint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z-eus/zeus_custom_waypoint
- Repository: https://github.com/z-eus/zeus_custom_waypoint

## Overview

1. **What this repo is**
   - A small **FiveM resource** named **Zeus Custom Waypoint**.
   - Its purpose is to replace/augment the default GTA/FiveM waypoint experience with configurable visuals: line color, blip, marker, and marker/blip styles.

2. **Top-level architecture**
   - The repo is intentionally minimal: one **manifest** (`fxmanifest.lua`), one **configuration file** (`config.lua`), and one **client script** (`client/client.lua`).
   - This strongly suggests a **client-only resource** with no server logic, persistence layer, or external service dependency.

3. **Runtime boundary**
   - All behavior happens on the **player client** in the FiveM runtime.
   - The script reads the player’s map waypoint position, then draws its own route/marker/blip effects locally.
   - Because it reconstructs the waypoint as a custom route, it can affect other scripts that expect the original waypoint semantics.

4. **Manifest / resource boundary**
   - `fxmanifest.lua` defines the resource for FiveM and wires together the config and client code.
   - This is the deployment boundary: when the resource is ensured in `server.cfg`, the client script becomes active for each player.

5. **Configuration subsystem**
   - `config.lua` is the main tuning surface.
   - The README indicates most behavior is configurable there: waypoint color, blip selection, blip style/color, marker type/color/style, and debug behavior.
   - This file is the separation point between the core logic and server/operator customization.

6. **Core waypoint processing**
   - `client/client.lua` is the functional center of the repo.
   - It likely monitors when the player sets or clears a map waypoint, captures the waypoint coordinates, and then creates a custom route from those coordinates.
   - The script also handles the lifecycle of that custom waypoint: creation, updates, deletion, and automatic cleanup when the player reaches the destination.

7. **Visual rendering subsystem**
   - The resource layers multiple visual cues on top of the waypoint:
     - **route line color**
     - **destination blip**
     - **3D marker**
   - The blip/marker options are stylistic overlays rather than separate gameplay systems, and they are tied to the waypoint endpoint.

8. **Input and lifecycle controls**
   - The README notes the waypoint can be deleted with a **key combination**, so the client script includes input handling and state reset behavior.
   - There is also automatic removal when the character reaches the marked position, which means the script tracks proximity to the target and tears down visuals on arrival.

9. **Debug / development support**
   - v0.2 added **debug**, implying the client script has optional logging or on-screen diagnostics controlled by config.
   - This is useful for validating waypoint capture, route creation, and cleanup without changing the resource’s runtime architecture.

10. **Dependency and deployment model**
   - The dependency is listed as **Standalone**, meaning it does not rely on a framework like ESX/QBCore.
   - That makes the resource portable across FiveM servers, with the only required integration being resource installation and `ensure Zeus_Custom_Waypoint`.

11. **Data flow summary**
   - Player sets waypoint on map → client script reads waypoint coordinates → script builds a custom route and visual endpoint effects → player travels toward target → script removes or resets the custom waypoint when cleared or reached.
   - No server round-trip is implied; the data flow is local and ephemeral.

12. **Important architectural constraint**
   - Because the script substitutes its own route handling, any other code that depends on the native waypoint location may see different behavior.
   - This is the key integration boundary for diagramming: the resource intercepts/represents waypoint intent, not just cosmetic rendering.

Main entry points: [`client/client.lua`](https://github.com/z-eus/zeus_custom_waypoint/blob/main/client/client.lua) (Client script), [`fxmanifest.lua`](https://github.com/z-eus/zeus_custom_waypoint/blob/main/fxmanifest.lua) (fxmanifest), [`config.lua`](https://github.com/z-eus/zeus_custom_waypoint/blob/main/config.lua) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_resource{{"Resource"}}
  node_fxmanifest["fxmanifest<br/>[fxmanifest.lua]"]
end

subgraph group_runtime["Client runtime"]
  node_client["Client script<br/>runtime script<br/>[client.lua]"]
  node_capture(("Waypoint capture<br/>input monitor"))
  node_route["Route builder<br/>waypoint logic"]
  node_visuals["Visual layers<br/>rendering"]
  node_controls(("Input reset<br/>lifecycle control"))
  node_arrival(("Arrival cleanup<br/>proximity check"))
  node_debug(("Debug<br/>diagnostics"))
end

subgraph group_tuning["Config"]
  node_config["Config<br/>settings<br/>[config.lua]"]
end

node_resource -->|"loads"| node_fxmanifest
node_fxmanifest -->|"includes"| node_config
node_fxmanifest -->|"starts"| node_client
node_config -->|"tunes"| node_client
node_client -->|"reads"| node_capture
node_capture -->|"feeds"| node_route
node_route -->|"renders"| node_visuals
node_client -->|"handles"| node_controls
node_client -->|"checks"| node_arrival
node_client -->|"reports"| node_debug
node_controls -->|"resets"| node_route
node_arrival -->|"cleans"| node_route

click node_fxmanifest "https://github.com/z-eus/zeus_custom_waypoint/blob/main/fxmanifest.lua"
click node_config "https://github.com/z-eus/zeus_custom_waypoint/blob/main/config.lua"
click node_client "https://github.com/z-eus/zeus_custom_waypoint/blob/main/client/client.lua"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_resource,node_fxmanifest toneBlue
class node_client,node_capture,node_route,node_visuals,node_controls,node_arrival,node_debug toneAmber
class node_config toneMint
```

## Components

### Deployment

Resource boundary and wiring for FiveM.

- **Resource**: fiveM resource · Client-only waypoint resource boundary.
- [fxmanifest](https://github.com/z-eus/zeus_custom_waypoint/blob/main/fxmanifest.lua): manifest · Declares the resource and loads shared/client code. · `fxmanifest.lua`

### Client runtime

Local waypoint handling and rendering on each player client.

- [Client script](https://github.com/z-eus/zeus_custom_waypoint/blob/main/client/client.lua): runtime script · Core client-side waypoint controller. · `client/client.lua`
- **Waypoint capture**: input monitor · Reads the map waypoint position when the player sets or clears it.
- **Route builder**: waypoint logic · Creates and updates the custom route from captured coordinates.
- **Visual layers**: rendering · Draws route color, destination blip, and marker effects.
- **Input reset**: lifecycle control · Handles key-based waypoint deletion and state reset.
- **Arrival cleanup**: proximity check · Removes the custom waypoint when the player reaches the target.
- **Debug**: diagnostics · Optional logging or diagnostics for development and validation.

### Config

Operator-facing settings for visuals and behavior.

- [Config](https://github.com/z-eus/zeus_custom_waypoint/blob/main/config.lua): settings · Main tuning surface for waypoint visuals and debug behavior. · `config.lua`

## Connections

- Resource → fxmanifest: loads · The resource is defined by the manifest.
- fxmanifest → Config: includes · Manifest wires in configuration.
- fxmanifest → Client script: starts · Manifest loads the client script.
- Config → Client script: tunes · Client behavior is driven by config values.
- Client script → Waypoint capture: reads · The script monitors waypoint changes.
- Waypoint capture → Route builder: feeds · Captured coordinates become the custom route target.
- Route builder → Visual layers: renders · Route state drives blip and marker overlays.
- Client script → Input reset: handles · Client responds to key-based clearing.
- Client script → Arrival cleanup: checks · Client removes the waypoint when the player arrives.
- Client script → Debug: reports · Optional diagnostics help validate state transitions.
- Input reset → Route builder: resets · Manual deletion clears the active route.
- Arrival cleanup → Route builder: cleans · Arrival tears down the active waypoint visuals.