> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-weapon-studio/developers.md).

# For developers

CAS Weapon Studio for RedM developers. The read-only GlobalState bag wsSkins that says which skin, kill notches and damage tune each player's weapons carry, the weapon keys and the database tables.

The Weapon Studio has no exports for other scripts to call. What each player's weapons carry is public state any script can read.

{% hint style="warning" %}
The state bag is read-only. Only the server side of `cas-weaponstudio` writes it. Do not set it from your own script: the next refresh overwrites your value, and other players' games draw from it.
{% endhint %}

## The state bag

The server keeps one bag per player in `GlobalState`, under `wsSkins:<serverId>`.

```lua
GlobalState["wsSkins:12"] = {
    cattleman  = { slot = "003", designId = 7, kills = 12 },
    winchester = { kills = 4 },
    schofield  = { slot = "011", designId = 21, dmg = 1.2 },
}
```

* The key of each entry is the weapon key (`cattleman`, `winchester` and so on). The full list is in [Designing skins](/script-documentation/cas-weapon-studio/designing.md#the-weapons).
* The bag is `nil` when the player's weapons carry nothing, when the player has no character yet, and after they leave.
* A weapon model with no skin, no notches and no tune has no entry.

### Fields

Every field is optional. An entry holds only what applies.

| Field      | Type                              | Meaning                                                                                                                                       |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `slot`     | string, three digits (`"003"`)    | The skin slot on this weapon model. The skin's files are `cas_ws_s003.ytd` and `cas_ws_s003_pKK.ydr`                                          |
| `designId` | number                            | The design's `id` in `cas_weaponskin_designs`. Set together with `slot`                                                                       |
| `kills`    | number, 1 to `Config.Notches.max` | The kill notches on this weapon model. Absent at zero or when notches are off                                                                 |
| `dmg`      | number                            | The damage tune of a custom gun the character owns for this weapon model (1.0 = the game's own). Absent at 1.0 or when custom weapons are off |

Only a skin the character may still use is in the bag: bought, a gift, their job's, or one that came with a custom gun. Only live skins are in it.

### When it changes

The server builds a player's bag again when:

* the player's game asks for it (a few seconds after joining, and after the character is selected on VORP or loaded on RSG),
* the player puts a skin on, takes one off or buys a custom gun,
* a kill adds a notch, or the player smooths the notches off,
* staff delete a design or save a hand-out (every online player's bag is built again).

### Reading it

On a client:

```lua
local bag = GlobalState["wsSkins:" .. GetPlayerServerId(PlayerId())]
local skin = bag and bag.cattleman
if skin and skin.slot then
    print(("my Cattleman wears design %d in slot %s"):format(skin.designId, skin.slot))
end
```

On the server:

```lua
local bag = GlobalState["wsSkins:" .. source]
local kills = bag and bag.cattleman and bag.cattleman.kills or 0
```

Watching for changes:

```lua
AddStateBagChangeHandler(nil, "global", function(_, key, value)
    if key:sub(1, 8) == "wsSkins:" then
        local serverId = tonumber(key:sub(9))
        -- value is the new bag, or nil
    end
end)
```

## How a skin is drawn

Useful when you look for a conflict with another script.

* A skin is a set of small props attached to the weapon object: one for the body, one per moving part, one per gunsmith part the weapon carries. 6 to 14 by weapon.
* Every client makes these props itself for the players within `Config.DrawDistance`. They are local objects, not networked.
* Nothing of the weapon is replaced. The weapon's own model and textures stay as they are.
* Kill notches are two more local props, one on each side.

| Name                                                  | What it is                                                                          |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `cas_ws_s001` to `cas_ws_s060`                        | The skin slots. Each is a texture dictionary `cas_ws_sNNN.ytd` in `stream/designs/` |
| `cas_ws_sNNN_pKK`                                     | The part props of slot `NNN` (`KK` is the part number)                              |
| `cas_ws_tally_s_NN`, `cas_ws_tally_l_NN`              | The notch props for a count of `NN` (01 to 30), in a short arm and a long arm size  |
| `stream/props/cas_ws_props.ytyp`, `cas_ws_tally.ytyp` | The archetypes of all of the above                                                  |

Do not stream a texture dictionary named `cas_ws_sNNN` from another resource. The studio sees it and leaves that slot unused.

## The CAS Gunsmith bridge

CAS Gunsmith's Skins tab talks to the studio through two local client events. It is the one channel meant for another script, and it stays the same in 1.x.

| Event                       | Who sends it | Arguments                                                                                                                                                                                                                                   |
| --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cas-weaponstudio:gunsmith` | CAS Gunsmith | `id, op, data`. `op` is `list`, `try`, `clear`, `buy`, `apply` or `remove`. `data` holds `town` (a `Config.Towns` id), `entity` (the weapon object on the bench), `slot` and `model` (for `try`), `designId` (for `buy`, `apply`, `remove`) |
| `cas-gunsmith:weaponstudio` | The studio   | `id, ok, result`: one answer per request. `list` answers `{ key, shop, owned }` (`key` false when the object is not a weapon of the studio); a refusal answers `{ code, text }`                                                             |

`try` shows a skin on any weapon object the client made itself, the same way the skin book shows it on the weapon in the hand. One preview at a time; `clear` takes it off. Buying, putting on and taking off go through the same server checks as the skin book.

## Database tables

All tables are made on the first start. Times are milliseconds since 1970. `owner` is the character: `vorp:<charIdentifier>` on VORP, `rsg:<citizenid>` on RSG, the player's license on standalone.

### cas\_weaponskin\_designs

| Column                                               | Meaning                                                           |
| ---------------------------------------------------- | ----------------------------------------------------------------- |
| `id`                                                 | The design id                                                     |
| `name`                                               | The name, up to 48 letters                                        |
| `target`                                             | The weapon, as `weapon_<key>` (`weapon_cattleman`)                |
| `kind`, `part`                                       | Always `weapon` and `skin`                                        |
| `slot_id`, `slot_albedo`                             | The slot number and name (`cas_ws_s003`) once exported            |
| `pending_albedo`, `pending_built_at`                 | The slot of an update that waits for the restart                  |
| `layers`                                             | The layers as JSON. Pictures are kept as `pic:<hash>`             |
| `thumb`                                              | The preview picture of the saved design                           |
| `live_name`, `live_thumb`                            | The name and picture the book shows: the look that is in the game |
| `next_name`, `next_thumb`                            | The look of the last export, until it goes live                   |
| `status`                                             | `draft`, `waiting`, `live` or `missing`                           |
| `built_at`, `created_by`, `created_at`, `updated_at` | When it was built, who made it, when                              |

### cas\_weaponskin\_handout

| Column                   | Meaning                                                                |
| ------------------------ | ---------------------------------------------------------------------- |
| `design_id`              | The design                                                             |
| `shop`, `price`, `towns` | Sold at gunsmiths (0 or 1), the price, the town ids as a JSON list     |
| `job`, `jobs`, `grade`   | Free for jobs (0 or 1), the job names as a JSON list, the lowest grade |
| `player`, `players`      | Given to players (0 or 1), the characters as a JSON list               |

### cas\_weaponskin\_pictures

| Column | Meaning                   |
| ------ | ------------------------- |
| `hash` | The picture's SHA-1       |
| `data` | The picture as a data URL |

### cas\_weaponskin\_owned

| Column               | Meaning                                                                        |
| -------------------- | ------------------------------------------------------------------------------ |
| `owner`, `design_id` | Which character owns which design                                              |
| `source`             | `shop` (bought), `gift` (given by staff) or `edition` (came with a custom gun) |
| `created_at`         | When                                                                           |

A job's skins are never stored here.

### cas\_weaponskin\_applied

| Column       | Meaning                                               |
| ------------ | ----------------------------------------------------- |
| `owner`      | The character                                         |
| `holder`     | What the skin is on: `w:<weapon key>` (`w:cattleman`) |
| `part`       | Always `skin`                                         |
| `design_id`  | The design that is on                                 |
| `updated_at` | When                                                  |

One row per character and weapon model.

### cas\_weaponskin\_kills

| Column           | Meaning                          |
| ---------------- | -------------------------------- |
| `owner`, `model` | The character and the weapon key |
| `kills`          | The notch count                  |

### cas\_weaponskin\_editions

| Column                      | Meaning                                           |
| --------------------------- | ------------------------------------------------- |
| `id`, `name`, `description` | The custom gun                                    |
| `weapon`                    | The base weapon's key                             |
| `design_id`                 | Its skin, or `NULL`                               |
| `damage`                    | The damage tune (1 = the game's own)              |
| `price`, `towns`            | The price and the town ids as a JSON list         |
| `stock`                     | The size of a limited run, `NULL` for an open run |
| `sold`                      | How many were sold                                |
| `enabled`                   | On sale (1) or off (0)                            |
| `created_at`, `updated_at`  | When                                              |

### cas\_weaponskin\_edition\_owned

| Column                | Meaning                          |
| --------------------- | -------------------------------- |
| `owner`, `edition_id` | Which character bought which gun |
| `number`              | The gun's number in the run      |
| `created_at`          | When                             |

{% hint style="info" %}
Read these tables freely. Change them only when the server is stopped: the running script keeps its own picture of slots and files, and a row changed under it can leave a slot unused or a skin without files.
{% endhint %}

## Not an API

The server exports `wsBridgeGetPlayer`, `wsBridgeRemoveMoney`, `wsBridgeAddMoney`, `wsBridgeIsAdmin`, `wsBridgeCanCarryWeapon`, `wsBridgeGiveWeapon` and `wsConfig` are the script's own bridge between its Lua and JavaScript halves. The `cas-weaponstudio:*` events are its own channel. Do not call them: they can change in any version.
