# Client Locker Usage Guide

The client locker addon manages personal locker display state, local locker
container behavior, and virtual arsenal unlock state.

## Repositories

`forge_client_locker_fnc_initRepository` creates `GVAR(LockerRepository)`.

`forge_client_locker_fnc_initVARepository` creates `GVAR(VARepository)`.

Initialize locker state:

```sqf
GVAR(LockerRepository) call ["init", []];
GVAR(VARepository) call ["init", []];
```

## Locker Container Flow

The repository searches mission namespace variables whose names contain
`locker` and refer to objects. For each server/mission locker object, it creates
a local `Box_NATO_Equip_F` at the same position and attaches container event
handlers.

On container open:

- the local container is cleared
- cached locker items are inserted into the container
- over-capacity warnings are emitted when the item count is above 25

On container close:

- cargo, nested container items, and weapon attachments are read back
- the new locker map is sent to the server with the override request
- the local repository cache is updated

## Virtual Arsenal Flow

The virtual arsenal repository creates a local `FORGE_Locker_Box` and requests
virtual arsenal unlocks from the server.

As sync data arrives, it applies unlocks through ACE Arsenal:

<table>
<thead>
  <tr>
    <th>
      Data key
    </th>
    
    <th>
      Client behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      Add virtual items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        weapons
      </code>
    </td>
    
    <td>
      Add virtual weapons.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        magazines
      </code>
    </td>
    
    <td>
      Add virtual magazines.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        backpacks
      </code>
    </td>
    
    <td>
      Add virtual backpacks.
    </td>
  </tr>
</tbody>
</table>

The actor menu opens the virtual locker with:

```sqf
[FORGE_Locker_Box, player, false] spawn ace_arsenal_fnc_openBox;
```

## Server Events

The client repository sends requests for:

- locker initialization
- locker save
- locker override after container close
- virtual arsenal initialization
- virtual arsenal save

The server locker addon and extension own the saved locker and virtual arsenal
state.

## Mission Setup

Mission locker objects must be placed into `missionNamespace` with a variable
name containing `locker`. The client creates local interactive containers from
those authoritative mission objects.

Example:

```sqf
missionNamespace setVariable ["forge_locker_alpha", _lockerObject, true];
```

## Related Guides

- [Locker Usage Guide](/server-modules/locker)
- [Owned Storage Usage Guide](/server-modules/owned-storage)
- [Client Actor Usage Guide](/client-addons/actor)