# zyrox-client/zyrox-gimkit-client architecture

> Architecture diagram of the GitHub repository zyrox-client/zyrox-gimkit-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zyrox-client/zyrox-gimkit-client
- Repository: https://github.com/zyrox-client/zyrox-gimkit-client

## Overview

1. **What this repo is**
   - `Zyrox client` is a **client-side Gimkit mod/userscript**. It runs inside the browser on `gimkit.com` and augments the game UI and game behavior.
   - There is **no application server** in this repository; the whole architecture is browser-injected code plus optional extension packaging.

2. **Primary runtime entrypoint**
   - The main product is `zyrox-base.js`, described in the README as the **main userscript file**.
   - That file is the core runtime that loads into the Gimkit page and coordinates the client features.

3. **Browser-extension packaging boundary**
   - `extension/zyrox-client/` is the extension-form version of the same client.
   - `manifest.json` declares the extension, while `content.js` and `inject.js` form the usual split between:
     - a **content script** running in the extension sandbox, and
     - an **injected page-context script** that can interact with the site’s own JS/DOM more directly.
   - This boundary matters because many game hooks require page-context access that a content script alone cannot provide.

4. **Page integration flow**
   - The client’s control flow is: **browser loads Gimkit page → extension/userscript injects client code → client attaches to page DOM, game state, and network traffic → modules react and render overlays or automation**.
   - The repo is therefore centered on **runtime interception and augmentation**, not on a traditional front-end app lifecycle.

5. **Game-state and packet layer**
   - `packetsniffer/packetsniffer.js` is a dedicated **debug/inspection tool**.
   - The README says it decodes traffic for both **blueboat** and **colyseus** modes, so packet decoding is a key lower-level boundary in the architecture.
   - This layer is likely the main source of authoritative game events consumed by higher-level modules.

6. **Feature/module layer**
   - The `tests/` directory contains many standalone scripts such as `esp.js`, `hide-popup.js`, `classic-autoanswer.js`, `classic-upgrade-hud.js`, and `ability-test.js`.
   - Despite the name, these appear to be **example/reference feature modules** and scenario-specific client behaviors rather than an automated test suite.
   - The module set suggests the client is organized around **feature plug-ins** for different Gimkit modes and utilities.

7. **UI overlay and HUD augmentation**
   - Several example scripts imply an overlay/UI subsystem: `classic-upgrade-hud.js`, `esp.js`, `hide-popup.js`, and `drawit-dump.js`.
   - These features likely sit on top of the game UI, adding information displays, suppressing disruptive UI, and rendering assistive visuals.

8. **Automation and game-mode specialization**
   - Scripts like `classic-autoanswer.js` and `ability-test.js` indicate **mode-specific automation** built on top of game state and packet data.
   - The repo is not generic UI tooling; it is tailored to specific Gimkit game modes and mechanics.

9. **External dependencies and distribution**
   - The client is distributed through **GreasyFork** as a userscript and through **Firefox Add-ons / Edge Add-ons** as an extension.
   - The README also links to a GitHub Pages install site and the Gimkit target site itself, which are relevant external touchpoints for deployment and use.

10. **Assets and non-code support files**
   - `images/` contains branding assets used by the README and likely the extension/client UI.
   - `LICENSE` and `PRIVACY POLICY` define the legal boundary of the project; they are important for the public distribution model but not part of runtime behavior.

11. **How to diagram it**
   - A good architecture diagram would show:
     - **Gimkit web app** as the external host,
     - **userscript/extension wrapper** as the injection boundary,
     - **core Zyrox client** as the feature orchestrator,
     - **packet sniffing / game-state decoding** as the lower-level input source,
     - **module features** as consumers of that state,
     - and **HUD/overlay/automation** as the outward-facing effects in the page.

Main entry points: [`tests`](https://github.com/zyrox-client/zyrox-gimkit-client/tree/main/tests) (Feature scripts), [`README.md`](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/README.md) (Docs), [`zyrox-base.js`](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/zyrox-base.js) (Userscript shell), [`extension/zyrox-client/manifest.json`](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/manifest.json) (Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_userscript_shell["Userscript shell<br/>entry boundary<br/>[zyrox-base.js]"]
  node_extension_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
  node_content_script["Content script<br/>extension bridge<br/>[content.js]"]
  node_page_injector["Page injector<br/>page bridge<br/>[inject.js]"]
  node_core_client["Zyrox core<br/>client orchestrator<br/>[zyrox-base.js]"]
end

subgraph group_group_input["Game Input"]
  node_packet_sniffer[("Packet sniffer<br/>protocol decoder<br/>[packetsniffer.js]")]
  node_game_state{{"Game state<br/>event/state layer"}}
end

subgraph group_group_features["Feature Modules"]
  node_feature_modules["Feature scripts<br/>module set"]
  node_esp_feature["ESP<br/>overlay module<br/>[esp.js]"]
  node_autoanswer_feature["Autoanswer<br/>automation module"]
  node_hud_feature["HUD upgrade<br/>ui module"]
  node_popup_feature["Hide popup<br/>ui module<br/>[hide-popup.js]"]
  node_ability_feature["Ability test<br/>mode module<br/>[ability-test.js]"]
end

subgraph group_group_support["Support"]
  node_images_assets["Images<br/>asset pack"]
  node_readme_docs["Docs<br/>project documentation<br/>[README.md]"]
end

node_gimkit_web(("Gimkit page<br/>external host"))

node_gimkit_web -->|"loads"| node_userscript_shell
node_gimkit_web -.->|"installs"| node_extension_manifest
node_extension_manifest -->|"declares"| node_content_script
node_content_script -->|"injects"| node_page_injector
node_page_injector -->|"boots"| node_core_client
node_userscript_shell -->|"starts"| node_core_client
node_core_client -->|"reads events"| node_packet_sniffer
node_packet_sniffer -->|"derives"| node_game_state
node_game_state -->|"feeds"| node_feature_modules
node_feature_modules -->|"includes"| node_esp_feature
node_feature_modules -->|"includes"| node_autoanswer_feature
node_feature_modules -->|"includes"| node_hud_feature
node_feature_modules -->|"includes"| node_popup_feature
node_feature_modules -->|"includes"| node_ability_feature
node_esp_feature -->|"renders on"| node_gimkit_web
node_hud_feature -->|"updates UI"| node_gimkit_web
node_popup_feature -->|"suppresses"| node_gimkit_web
node_autoanswer_feature -->|"automates"| node_gimkit_web
node_ability_feature -->|"interacts"| node_gimkit_web
node_readme_docs -.->|"documents"| node_userscript_shell
node_readme_docs -.->|"documents"| node_extension_manifest
node_images_assets -.->|"illustrates"| node_readme_docs

click node_userscript_shell "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/zyrox-base.js"
click node_extension_manifest "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/manifest.json"
click node_content_script "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/content.js"
click node_page_injector "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/inject.js"
click node_core_client "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/zyrox-base.js"
click node_packet_sniffer "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/packetsniffer/packetsniffer.js"
click node_feature_modules "https://github.com/zyrox-client/zyrox-gimkit-client/tree/main/tests"
click node_esp_feature "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/esp.js"
click node_autoanswer_feature "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/classic-autoanswer.js"
click node_hud_feature "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/classic-upgrade-hud.js"
click node_popup_feature "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/hide-popup.js"
click node_ability_feature "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/ability-test.js"
click node_images_assets "https://github.com/zyrox-client/zyrox-gimkit-client/tree/main/images"
click node_readme_docs "https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/README.md"

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_userscript_shell,node_extension_manifest,node_content_script,node_page_injector,node_core_client toneBlue
class node_packet_sniffer,node_game_state toneAmber
class node_feature_modules,node_esp_feature,node_autoanswer_feature,node_hud_feature,node_popup_feature,node_ability_feature toneMint
class node_images_assets,node_readme_docs toneRose
class node_gimkit_web toneNeutral
```

## Components

### Runtime

Injected browser client and extension packaging

- [Userscript shell](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/zyrox-base.js): entry boundary · Top-level browser-injected client entrypoint · `zyrox-base.js`
- [Manifest](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/manifest.json): extension config · Defines the extension packaging and permissions · `extension/zyrox-client/manifest.json`
- [Content script](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/content.js): extension bridge · Sandboxed extension-side runtime that injects into the page · `extension/zyrox-client/content.js`
- [Page injector](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/extension/zyrox-client/inject.js): page bridge · Moves code into Gimkit page context for direct hooks · `extension/zyrox-client/inject.js`
- [Zyrox core](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/zyrox-base.js): client orchestrator · Coordinates page integration, modules, and runtime behavior · `zyrox-base.js`

### Game Input

Packet decoding and event capture

- [Packet sniffer](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/packetsniffer/packetsniffer.js): protocol decoder · Decodes blueboat and colyseus traffic into game events · `packetsniffer/packetsniffer.js`
- **Game state**: event/state layer · Derived match state consumed by features

### Feature Modules

Example and mode-specific client behaviors

- [Feature scripts](https://github.com/zyrox-client/zyrox-gimkit-client/tree/main/tests): module set · Mode-specific scripts and client behaviors under tests/ · `tests`
- [ESP](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/esp.js): overlay module · Enemy/item visibility overlay behavior · `tests/esp.js`
- [Autoanswer](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/classic-autoanswer.js): automation module · Classic mode answering automation · `tests/classic-autoanswer.js`
- [HUD upgrade](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/classic-upgrade-hud.js): ui module · Augments the in-game HUD and status display · `tests/classic-upgrade-hud.js`
- [Hide popup](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/hide-popup.js): ui module · Suppresses disruptive game popups · `tests/hide-popup.js`
- [Ability test](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/tests/ability-test.js): mode module · Specialized gameplay automation and interaction logic · `tests/ability-test.js`

### Support

Docs, assets, and legal files

- [Images](https://github.com/zyrox-client/zyrox-gimkit-client/tree/main/images): asset pack · Branding and UI assets used by docs and client · `images`
- [Docs](https://github.com/zyrox-client/zyrox-gimkit-client/blob/main/README.md): project documentation · Repository overview, installation, and usage guidance · `README.md`

### Other components

- **Gimkit page**: external host · Browser host application where Zyrox is injected

## Connections

- Gimkit page → Userscript shell: loads · The browser loads the injected userscript on Gimkit
- Gimkit page → Manifest: installs · Extension packaging targets the Gimkit page
- Manifest → Content script: declares · Manifest wires the content script into the page
- Content script → Page injector: injects · Bridges from extension sandbox into page context
- Page injector → Zyrox core: boots · Injected page-context code starts the main client
- Userscript shell → Zyrox core: starts · Userscript entrypoint initializes the core runtime
- Zyrox core → Packet sniffer: reads events · Core logic consumes decoded traffic and game signals
- Packet sniffer → Game state: derives · Protocol data is converted into higher-level match state
- Game state → Feature scripts: feeds · Shared state is consumed by feature plug-ins
- Feature scripts → ESP: includes · Representative overlay feature
- Feature scripts → Autoanswer: includes · Representative automation feature
- Feature scripts → HUD upgrade: includes · Representative HUD feature
- Feature scripts → Hide popup: includes · Representative suppression feature
- Feature scripts → Ability test: includes · Representative mode-specialized feature
- ESP → Gimkit page: renders on · Overlay effects appear in the live game page
- HUD upgrade → Gimkit page: updates UI · HUD augmentations are rendered in the browser page
- Hide popup → Gimkit page: suppresses · Client removes or hides intrusive page UI
- Autoanswer → Gimkit page: automates · Automation interacts with the live game experience
- Ability test → Gimkit page: interacts · Mode-specific logic drives game actions in-page
- Docs → Userscript shell: documents · README describes the main userscript entrypoint
- Docs → Manifest: documents · README also covers extension installation and use
- Images → Docs: illustrates · Images support branding and documentation
