# SIMs & carriers

Connect your city with SIMs, eSIMs, carriers, plans, mobile data and live cell towers.

## How phone numbers work

New phones have no number until a SIM is activated. The default in `config/sims.lua` is:

```lua
Config.AutoProvisionDefaultLine = false
```

Keep this setting if players should buy their own SIM. Setting it to `true` automatically creates a default line for brand-new phones. It does not remove existing lines.

A number only routes calls and messages to the phone holding its SIM. What is sent and received belongs to the phone's Nova Account (or the phone itself without one), so removing a SIM keeps the history, and moving a SIM to someone else's phone starts that number fresh for them.

## Carrier shops

Locations and products are configured in `config/shops.lua`, under `Config.CarrierShops`.

| Shop | Carrier | Sells at the counter | Map blip |
| --- | --- | --- | --- |
| Nova Mobile | `nova_mobile` | Blank SIMs, activation of a blank SIM on a plan, and eSIMs | Yes |
| Apex Wireless | `apex_wireless` | Blank SIMs, activation of a blank SIM on a plan, and eSIMs | Yes |
| Ghost Mobile | `ghost_mobile` | Timed burner eSIMs only | Hidden |

The receipt shows the new number, the activation code and the PUK once. Everything else is done in **SIM Manager → Carrier**, from anywhere: top-ups, data packs, bills, changing plan, custom numbers and replacement SIMs. The shop screen tells players so.

To move a shop, edit its existing `coords` and `heading`. You can also change the label and blip. In `products`, only `blank_sim`, `activate` and `esim` change what the counter sells. Keep `carrier` matched to an ID in `config/carriers.lua`.

```lua
-- Example fields inside an existing shop entry
coords = vector3(-655.0, -854.0, 24.5),
heading = 90.0,
```

Shops use `ox_target` when available and fall back to an **[E]** prompt. Players must be within 3 metres of a shop to buy; the server checks the distance.

Blank SIMs are also sold at the [phone stores](#/docs/wd_phone/devices?section=phone-stores), but are activated at a carrier shop.

Each SIM remembers the shop it was bought at. Police can look that up, with the buyer and the date, in [Subscriber records](#/docs/wd_phone/subscriber-records). Ghost Mobile keeps no records.

## Prices and plans

| File | What to change |
| --- | --- |
| `config/carriers.lua` | Names, number formats, supported plans and custom-number pricing |
| `config/plans.lua` | Plans, call costs, data allowances, data packs |
| `config/shops.lua` | Blank SIM and replacement SIM fees |
| `config/banking.lua` | How carrier charges are paid |

The included plans:

| Plan | Carrier | Type | Activation | Monthly | Calls | Data |
| --- | --- | --- | --- | --- | --- | --- |
| Nova Basic | Nova Mobile | Prepaid, 100 credit | 250 | — | 1 per minute | 500 MB |
| Unlimited Plus | Nova Mobile | Monthly | 750 | 500 | Unlimited | 10 GB |
| Business Pro | Nova Mobile | Business | 1000 | 900 | Unlimited | 25 GB |
| Apex Go | Apex Wireless | Prepaid, 150 credit | 200 | — | 1 per minute | 750 MB |

Ghost Mobile burners are priced by how long they last instead; see [Burner eSIMs](#burner-esims).

Prepaid users top up credit in SIM Manager → Carrier. Calls are charged for every started minute while they last, and a call ends when the credit runs out. A line with no credit left still receives calls. In a group call, whoever rang a person pays for that person's minutes. Set `Config.Prepaid.deductCalls = false` in `config/plans.lua` to make calls free.

Monthly plans are billed every 30 days, and the bill is paid automatically when the owner is online. Otherwise the phone gets a "bill due" notification and the line has a 48-hour grace period, in which it works normally. After that the line is **suspended**: it cannot make or receive calls or send messages until the bill is paid with **Pay Bill** in SIM Manager → Carrier, which also brings the plan's data back. Emergency calls still work, since they need no SIM. Paying only lifts a suspension caused by the bill. One placed by another resource with the `SuspendSim` export stays until `ReactivateSim`.

Fees: a blank SIM costs 100, a replacement SIM 500 and a custom number 5000. A custom number is bought in SIM Manager → Carrier after checking that it is free. Voicemail numbers, `911` and numbers starting with `000` are reserved, and a number given up rests for 72 hours before anyone else can buy it. Burner eSIMs cannot buy one.

## Mobile data

Calls cost credit. Everything that goes online uses **data** instead: messages and attached photos, video calls, Mail, Echo, Snapgram, Ember, [Clips](#/docs/wd_phone/clips), [Shade](#/docs/wd_phone/shade), News, Marketplace, Business, City, the Wallet, Music streaming, Arcade leaderboards, Assist's AI answers, custom apps such as Browser, and Nova Store downloads.

- A phone is online with Mobile Data on, airplane mode off, a usable SIM with service, and data left.
- Each plan's allowance comes back every 30 days.
- **Prepaid** SIMs keep going after the allowance, paying 1 credit per MB. A top-up also adds 2 MB per $1.
- **Monthly and business** plans stop when the data runs out, until the plan renews or the player buys a **data pack** in SIM Manager: 500 MB for 100, 2 GB for 300 or 10 GB for 1000.
- The phone warns when less than 50 MB is left, and again when the data is used up.
- A joined Wi-Fi network costs no data. See [Batteries & accessories](#/docs/wd_phone/accessories).
- A player can share their mobile data with nearby phones through **Personal Hotspot**. What the joined phones use comes out of the host's data and plan. See [Batteries & accessories](#/docs/wd_phone/accessories?section=personal-hotspot).
- **SIM Manager → Carrier** shows the data left, recent usage and the data packs. On Wolfden Phone Pro with two lines, Control Center → Mobile Data chooses which line pays for data.

Sizes are estimated by the server for each action; the phone never reports them. Change them, or turn data off entirely, in `Config.MobileData` in `config/plans.lua`. Some apps set their own sizes in their config files.

## Physical SIMs and eSIMs

Activate a blank physical SIM at a shop, then install it in SIM Manager. Installation takes the card out of the inventory; removing it gives the card back. Removal is blocked during an active call or with a full inventory.

eSIM codes are single-use and expire after 15 minutes by default (`Config.EsimActivationTtlSeconds`). The eSIM tab also lists **Your eSIMs**: every eSIM the character bought. One that is not in a phone installs in one tap, with no code, so a player can move an eSIM to a new phone. Removing an eSIM keeps its line and history.

Each model's limits are in `Config.SimCapabilities` in `config/sims.lua`, keyed by model:

| Model | Enabled lines | SIM card slot | eSIMs stored |
| --- | --- | --- | --- |
| Wolfden Phone (`nova`) | 1 | Yes | 1 |
| Wolfden Phone Pro (`nova_business`) | 2 | Yes | 4 |
| Wolfden Phone Secure (`nova_secure`) | 1 | No | 1, Ghost Mobile only |

Each installed SIM has a **Turn On This Line** switch. On Wolfden Phone, which has one line, turning a line on turns the other off, so a player can keep a SIM card and an eSIM and switch between them.

On Wolfden Phone Pro both lines ring and receive messages at the same time. **SIM Manager → Lines** sets the default line for calls and messages, or **Ask every time**, which shows a line picker before each call or message.

## Burner eSIMs

Ghost Mobile sells timed eSIMs only, with no SIM card. The player picks a duration and receives an activation code and a PUK:

| Duration | Price |
| --- | --- |
| 1 hour | 500 |
| 6 hours | 900 |
| 24 hours | 1500 |
| 3 days | 3500 |

The eSIM has a `777` number, always hides its caller ID, and expires once its time is up, with a warning five minutes before.

A burner works in the eSIM slot of any phone, not only Wolfden Phone Secure. It cannot be replaced, moved to another SIM or given a custom number.

Durations and prices are in `Config.SecureSimDurations` in `config/sims.lua`. Wolfden Phone Secure only accepts these eSIMs, and can swap one's number for a fresh `777` number; see [Wolfden Phone Secure](#/docs/wd_phone/nova-secure?section=new-number).

## PIN, PUK and lost SIMs

The SIM PIN is separate from the phone's lock PIN. A SIM with its PIN turned on cannot call, message, use data or ring until the PIN is entered after the phone turns on and after the SIM is put in a phone. By default, three incorrect SIM PIN attempts require the PUK, and ten incorrect PUK attempts permanently lock the SIM. These limits are in `Config.SimSecurity` in `config/sims.lua`; set `requirePinAfterReconnect = true` to also ask for the PIN when its holder reconnects.

**Replace SIM**, in SIM Manager → Carrier, gives a new card with the same number, plan, credit and data for a physical SIM installed in the phone, for 500. The old card stops working. It also works on a SIM locked for good by wrong PUKs. Burner eSIMs cannot be replaced, and a card the player no longer has cannot be replaced from the phone. If the new card does not fit in the inventory, nothing changes and the fee is refunded.

Players cannot move a number to another SIM themselves. Another resource can, with the `TransferNumber` export, which charges no fee; see [Exports & integrations](#/docs/wd_phone/exports).

## Signal, No SIM and No Service

**No SIM** means there is no enabled usable SIM. **No Service** means the phone cannot reach its carrier where the player stands. Neither means installation failed.

Coverage comes from [cell towers](#cell-towers) and from zones in `config/signal.lua`. Each carrier has its own coverage. Fewer bars make call audio worse and messages slower:

- A phone with No Service does not ring; the caller hears that it is unavailable, and the call shows as missed.
- A call drops after a few seconds with no service on either side.
- A message waits until the recipient has service. If it is not delivered within 60 seconds, the sender sees **Not Delivered** with Retry.

**Zones** in `Config.Signal.zones` override tower coverage in an area, such as a bunker with emergency calls only or a tunnel with no signal. A zone can also let only some carriers through, with `allowedCarriers = { ghost_mobile = true }`, or shut some out with `blockedCarriers`.

Emergency numbers (`911` by default) work without a SIM, credit or signal. Configure them in `Config.EmergencyNumbers`. Emergency calls can also be sent to your dispatch resource; see [Dispatch integrations](#/docs/wd_phone/configuration?section=dispatch-integrations).

## Cell towers

Towers are live. The four towers in `Config.Signal.towers` are only a starting point: they are added to the database on the first start, and from then on admins edit towers in game. Edits and deletions are kept across restarts.

**Edit towers in game.** Run `phoneadmin towers` (or choose **Cell towers** in the admin menu) as an admin:

1. **Add tower here** places the antenna where you stand. Give it a name, a radius and a strength for each carrier, from 0 (not served) to 2.
2. **Set access point here**, at the foot of the tower facing where the equipment cabinet should face. Without an access point, a tower cannot be sabotaged or repaired in the field.
3. Select a tower to **Edit** it, switch it off, **Move antenna here**, teleport to it, force damage or repair, or delete it.
4. **Coverage debug view** shows every tower's range on the map (green online, red damaged, grey switched off), dead zones, and the signal for each carrier where you stand.

**Sabotage.** At a tower's equipment cabinet, a player carrying a crowbar or a wrench can take the tower down after a 20-second progress bar. Every carrier it serves loses that coverage, and the cabinet throws sparks until it is repaired. On-duty police get an alert and a blip. A repaired tower cannot be sabotaged again for 30 minutes.

**Repair.** An on-duty `mechanic` fixes a damaged tower at its cabinet after 15 seconds and is paid 250. A player who sabotaged a tower is never paid for repairing it, and on-duty repair crews cannot sabotage at all.

Both use ox_target, or an **[E]** prompt without it. Players with no other tower in range lose signal, and their calls drop as usual.

Tune it in `config/towers.lua`:

| Setting | Default | What it does |
| --- | --- | --- |
| `enabled` | `true` | `false` keeps towers fixed to `Config.Signal.towers`, with no editing or sabotage |
| `damagedMultiplier` | `0.0` | A damaged tower's strength: `0` is a full outage, `0.3` weak signal |
| `autoRepairMinutes` | `0` | Repair damaged towers by themselves after this long; `0` waits for a crew |
| `sabotage.items` | `WEAPON_CROWBAR`, `WEAPON_WRENCH` | Tools that can sabotage; any one is enough. Empty needs no tool |
| `sabotage.cooldownMinutes` | `30` | Protection after a repair |
| `sabotage.alert.jobs` | `{ 'police' }` | Jobs alerted, with a blip for 180 seconds |
| `repair.jobs` / `repair.requireDuty` | `{ 'mechanic' }` / `true` | Who can repair |
| `repair.item` | `nil` | An item a repair uses up |
| `repair.pay` | `250` | Paid to the repairer |
| `accessProp` | `prop_elecbox_10` | The equipment cabinet model |

Use your inventory's item names: on qb-inventory, weapons are lower case, such as `weapon_crowbar`.

Admins can also run `phoneadmin towerdamage <towerId>` and `phoneadmin towerrepair <towerId>`; see [Admin tools](#/docs/wd_phone/admin). Every sabotage, repair and edit is logged. Other resources can react through the `wd_phone:server:towerSabotaged` and `wd_phone:server:towerRepaired` server events.

## Admin testing

The easiest test is the real one: give a phone, buy a SIM at a carrier shop and install it in SIM Manager.

For quicker testing, set `Config.Debug = true` in `config/shared.lua` on a test server. The console, and admins with the phone admin permission, then also have:

```text
wd_phone_givesim <id> [item] [carrier] [plan]
wd_phone_testesim <id> [carrier] [plan]
```

The first gives an activated physical SIM and prints its number. The second prints an eSIM activation code and its number. Replace `<id>` with a player's server ID; bracketed values are optional. Turn `Config.Debug` off again on your live server.