> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/weapons-editor/usage-guide.md).

# Usage guide

Open the editor with `/weaponeditor` (or your `Config.Keybind`). Close it with **Esc**; if the mouse stays locked use `/weaponeditor_close`.

## LIVE, HOT and RESTART

Every field belongs to one class. The class tells you **when** a change reaches the players.

| Class       | Fields                                                                                                                               | How                                                    | Applies                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
| **LIVE**    | Damage (or multiplier), spread, recoil (camera), explosion radius, 4 player-wide multipliers                                         | natives + `GlobalState['gwe:live']`                    | Immediately, for everyone; late joiners get it on spawn. |
| **HOT**     | Every other numeric `CWeaponInfo` tag (clip, fire rate, range, falloff, headshot, reload, HUD, ...), ammo (`CAmmoInfo`), attachments | `weapons_gwe.meta` / `weaponcomponents_gwe.meta` patch | **Next join (reconnect) or server restart.**             |
| **RESTART** | State of every HOT field (the client loads the patch on join)                                                                        | File in the patch (or in `generated/`)                 | Next join (reconnect) or server restart.                 |

{% hint style="info" %}
With `Config.HotReload = false` (default, recommended) HOT fields are labelled "Active on next join or restart" and saving shows "Saved: applies on next join (reconnect) or server restart."
{% endhint %}

## Editing a weapon

1. Pick a weapon from the list on the left. Use the search (**Ctrl+K**: weapon, hash or resource) and the filters (source, state, category). **↑ ↓** browse the list. Star a weapon to add it to **Favorites**.
2. Change values in the field groups: Damage, Headshot, Damage falloff, Accuracy, Recoil, Fire rate and clip, Reload, Range, Impact and projectile, Explosion, HUD stats, Ammo. Every field has a tooltip with its meaning and its meta tag.
3. Your edits are a **draft**. **Ctrl+Z / Ctrl+Y** undo and redo. You can restore the saved value or **Reset to vanilla** per field, or discard the weapon draft or all drafts.
4. Optional: enable **Local preview** to apply LIVE fields only to your own client while editing, before publishing.
5. Press **Apply**: LIVE fields apply immediately to all players, the rest is saved (HOT values reach players on the next join or restart).

{% hint style="warning" %}
**Ammo is a shared block**: changing max ammo changes every weapon that uses the same ammo type.
{% endhint %}

{% hint style="info" %}
A weapon without a meta block (for example one added with `Config.ExtraWeapons`) shows "No meta block: LIVE fields only". Weapons that do not exist on your game build are marked "Not available on this gamebuild".
{% endhint %}

### Damage on melee and explosive weapons

`Damage per shot` does not work for melee and explosive weapons. Use the **Damage multiplier** (`DamageMult`, 1.0 = unchanged): it is the only way to tune them.

## Charts: damage by distance, shots to kill, TTK

The editor shows damage by distance, **shots to kill** (body and head) and **time to kill**, using `Config.KillHealth` (default 120) as the reference. Model: health + armor = HP to remove; damage per shot = Damage x distance falloff x pellets (`BulletsInBatch`) x headshot multiplier (within `MaxHeadShotDistancePlayer`).

**Set damage** picks a target number of shots N and sets `Damage` to kill in exactly N shots (not N-1). If the required damage exceeds the field maximum it is clamped.

## Attachments (Components)

The **Components** tab edits the weapon's attachments: clip capacity of extended magazines, accuracy modifier (scopes, grips), damage modifier (suppressors), falloff range and damage modifiers (barrels, compensators), scope recoil and the HUD stat changes. Attachment fields are HOT and marked experimental.

## Player globals

The **Globals** tab holds 4 LIVE multipliers for every player:

| Field                   | Effect                                           |
| ----------------------- | ------------------------------------------------ |
| Weapon damage (global)  | Damage multiplier of all firearms (minimum 0.1). |
| Weapon defense (global) | Multiplier of firearm damage taken.              |
| Melee damage (global)   | Melee damage multiplier.                         |
| Melee defense (global)  | Multiplier of melee damage taken.                |

## Compare

The **Compare** tab shows 2 to 4 weapons side by side: damage by distance, shots to kill, time to kill, DPS, HUD stats and a table.

## Changes

The **Changes** tab lists the weapons already changed from vanilla and shows the draft vs saved vs vanilla diff.

## Presets

* Built-in presets: **Realistic**, **Arcade**, **Slow RP**. They cannot be changed. In built-in presets the numbers are multipliers applied to each weapon's base value.
* **Save as preset** stores your current values with a name. Admins can tick **Global preset (admin)**.
* Apply a preset to a weapon, to a category (**Apply to category**) or to everything. The preview tells you how many fields on how many weapons it changes.
* The preset is applied **immediately by the server** (not to the draft).
* Limits: `Config.Limits.maxPresets` (100 total) and `maxPresetsPerAuthor` (20 per author; admins have no cap).

## History

The **History** tab lists the saved versions. **Rollback** restores a version after a confirmation (admin). `Config.HistoryMax` (default 500) snapshots are kept.

## Import / Export

* **Export JSON**: the draft only, or all saved values; optionally include LIVE fields. Copy to the clipboard or download.
* **Export .meta**: download the values as a meta file.
* **Import**: paste JSON or choose a file, press **Verify**, then **Import**. Imported weapons go into the **draft**: review and Apply. Maximum size: `Config.Limits.maxImportBytes` (256 KB).

## Settings

The editor lets you change the UI language and the UI scale.

## Keyboard shortcuts

| Keys            | Action                                                    |
| --------------- | --------------------------------------------------------- |
| Ctrl+Z / Ctrl+Y | Undo / redo                                               |
| Ctrl+K          | Search                                                    |
| ↑ ↓             | Browse weapons                                            |
| Esc             | Close (asks for confirmation if you have unsaved changes) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/weapons-editor/usage-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
