# 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:

| Data key | Client behavior |
| --- | --- |
| `items` | Add virtual items. |
| `weapons` | Add virtual weapons. |
| `magazines` | Add virtual magazines. |
| `backpacks` | Add virtual backpacks. |

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](./LOCKER_USAGE_GUIDE.md)
- [Owned Storage Usage Guide](./OWNED_STORAGE_USAGE_GUIDE.md)
- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md)
