Configuration

This page lists every setting in oxide-phone, what it does in game, its default value, and where to find it in the /phone settings menu. Start with How Settings Work: the phone saves its settings in your database, so editing the config file does not always do what you expect.

How Settings Work

The Short Version

• The first time oxide-phone starts, it copies every setting from shared/config.lua into a database table called oxide_settings.
• From then on, the database decides. Editing shared/config.lua does not change a setting that is already saved in the database.
• To change settings after the first start, join the server as an admin and type /phone settings.
• Changes you save in that menu are stored in the database straight away, and almost all of them work immediately, without a restart.

The First Start

After the First Start

On every start after the first one, oxide-phone reads its settings from the database. The config file is only used in these cases:

• A setting missing from the database is copied in from shared/config.lua. This happens when a resource update adds a brand-new setting, or when you delete a setting's row from the database.
• A new option inside an existing group is filled in from shared/config.lua. For example, if an update adds a new option under Config.Battery, that one option is added and your other battery settings stay as they are.
• Lists are never merged. Lists such as Config.Items.phones, Config.Numbers.prefixes, Config.Evidence.jobs, Config.Evidence.stations, Config.Emergency.numbers, Config.DeadZones, Config.Store.preinstalled, Config.Home.wallpapers and Config.ModelSwaps are saved as a whole. After the first start, the whole list comes from the database.
• Reset to default in the menu puts a setting back to the value in shared/config.lua (see below).

When you update oxide-phone and the update replaces shared/config.lua, you lose nothing: your saved settings stay in the database.

Changing Settings in Game

Reset to default next to a setting puts it back to the value shared/config.lua had the last time the phone started. The reset is saved immediately. For settings that hold several options (such as Battery), the reset puts back all of them together.

Positions in the world (Forensics stations and charging stations) have two small buttons: the crosshair (Place in world) hides the menu so you can pick the spot in the world, and Teleport here takes you to a saved spot. A charging station is placed as a see-through copy of its model that you turn and put down.

Using the Config File After the First Start

If you prefer editing shared/config.lua, you need one extra step to push your change into the database:

When Changes Take Effect

Almost every setting applies as soon as you press Save Changes, for every player, with no restart. The exceptions:

Where Each Setting Is in the Menu

Config File: shared/config.lua

General

Config.Debug = false
Config.SettingsCommand = '/phone settings' -- named in warnings
Config.OpenKey = 'F1'

Menu: Device → General (OpenKey, up to 20 characters) and Advanced → Advanced on the Advanced tab (Debug, shown as Debug mode). Config.SettingsCommand has no place in the menu; leave it as it is.

Items

The inventory item names the phone reacts to. Each item must exist in your inventory (see Installation → Framework Setup).

Config.Items = {
    phones = { 'phone' },     -- every item listed opens as a phone
    sim = 'sim_card',         -- registered SIM
    burnerSim = 'burner_sim', -- unregistered SIM; '' disables burners
    powerbank = 'powerbank',  -- one-shot charge; '' disables the item
    wiper = 'phone_wiper',    -- secure wipe; '' disables it
}

Menu: Device → Items. Item names can be up to 60 characters. A name you add is ready to use as soon as you save.

Phone Numbers

Config.Numbers = {
    format = '@-###-####',
    prefixes = { '213', '310', '323', '424', '562', '626', '714', '818', '909', '949' },
}

Menu: Device → Numbers & SIMs → Phone numbers. Existing numbers never change. Players can type a number with or without dashes; the phone lays it out in your format.

SIM Cards

Config.Sim = {
    autoIssue = true,
    replacementCost = 0,
    replacementAccount = 'bank',
}

Menu: Device → Numbers & SIMs → SIM cards (Free SIM with a new phone, Replacement SIM price, Paid from).

Screen Lock

Config.Lock = {
    minLength = 4,
    maxLength = 6,
    maxAttempts = 5,        -- wrong passcodes in a row before a lockout
    lockoutSeconds = 300,   -- 5 minutes
}

Menu: Device → Security → Screen lock. Passcodes are stored scrambled (hashed), so nobody can read them back. Admins remove a forgotten one with /phone resetpin.

Battery

Batteries are off by default: phones never run flat.

Config.Battery = {
    enabled = false,          -- off: phones never run flat
    drainPerMinute = 0.2,     -- while switched on; 0.2 lasts about 8 hours
    inUsePerMinute = 0.6,     -- extra while the screen is open
    torchPerMinute = 0.4,     -- extra while the torch is on
    lowPowerFactor = 0.6,     -- Low Power multiplies every drain by this
    vehiclePerMinute = 3.0,   -- charge gained while sitting in a vehicle
    powerbankCharge = 50,     -- percent a powerbank adds
}

Menu: World → Battery. A flat or switched-off phone gets no calls, texts or mail (texts and mail wait) and cannot be traced.

Charging Stations

Kiosks where players charge their phones: the phone's oxide_phone_charger model. They only do something while batteries are on (Config.Battery.enabled). How players use them is in Features → Charging Stations.

Config.Chargers = {
    nearby = true,
    nearbyRadius = 3.0,
    nearbyPerMinute = 2.0,
    docking = true,
    dockPerMinute = 5.0,
    takeBack = 'anyone',      -- or 'owner'
    policeCanTake = true,
    stations = {},            -- { label = 'Name', coords = vector4(x, y, z, heading) }
}

Menu: World → Battery → Charging stations. Each option shows a short hint under its name. Changes, new stations included, take effect for everyone as soon as you save.

Place a station in game (this uses o-link's in-world placement):

The person button next to the crosshair takes you to a saved spot.

Use a station you placed with your own map tools: add a row the same way, and in step 4 aim at your station. The see-through station snaps onto it, so the spot matches it exactly. The phone then sees the model already there and doesn't spawn a second one. A station model on your map that isn't in this list charges nothing: the server only trusts its own list.

Move or remove a station: change its position or delete its row, then save. Phones lying on its pads go back to the players who left them, the next time they are online.

Calls

Calls need pma-voice. See Installation → Calls.

Config.Calls = {
    ringSeconds = 30,   -- an unanswered call ends after this
    ringRange = 15.0,   -- metres within which other players hear a phone ring
    ringSound = { name = 'Text_Arrive_Tone', set = 'Phone_SoundSet_Default', interval = 2500 },
    voicemailSeconds = 30,
    voicemailDays = 30,
    answerKey = 'RETURN',
    declineKey = 'BACK',
}

Menu: Device → Calls & Messages → Calls.

Texts

Config.Messages = {
    maxLength = 500,
    groupSize = 8,
    perMinute = 20,
    queueDays = 7,
    voiceSeconds = 60,
}

Menu: Device → Calls & Messages → Texts.

Contacts

Config.Contacts = {
    max = 200,
    shareRange = 3.0,
    shareSeconds = 60,
}

Menu: Device → Calls & Messages → Contacts. Contacts are stored on the phone, not on the character.

Mail

Config.Mail = {
    maxPerPhone = 200,
    pendingDays = 30,
    domain = 'phone.mail',
    perMinute = 6,
    perHour = 40,
    transactionWords = { 'bank', 'shop', 'store', 'receipt', 'invoice', 'payment' },
}

Menu: Device → Calls & Messages → Mail. Mail sent to a character without a phone waits and arrives on the next phone that holds one of their registered SIMs.

Photo Storage

The phone stores no photos itself. See Installation → Photos for setting up each service.

Config.Media = {
    provider = 'none',   -- 'none' | 'fivemanage' | 's3' | 'custom'
    maxKB = 2048,        -- largest photo
    perMinute = 6,       -- photos one player may upload per minute
    keepPerPhone = 500,  -- photos, videos and audio clips a phone can hold
    hosts = {},          -- extra hosts photos may come from (custom storage)
    video = {
        maxSeconds = 60,   -- longest clip (5-180)
        fps = 24,          -- 24 or 30
        kbps = 1200,       -- recording bitrate (500-3000)
        maxMB = 12,        -- largest clip
        perMinute = 3,     -- clips one player may upload per minute
        perPhoneMB = 250,  -- all the videos on one phone together
    },
    audio = { maxSeconds = 120, maxKB = 1024, perMinute = 3 },   -- voicemail and voice messages
    fivemanage = { endpoint = 'https://api.fivemanage.com/api/v3/file/presigned-url' },
    s3 = { endpoint = '', region = 'auto', bucket = '', publicUrl = '', prefix = 'phone' },
}

Menu: Device → Media → Photo storage (Video and Audio are inside it). The keys for Fivemanage and S3 go in server.cfg, never here. With Fivemanage, photos and videos are allowed from fivemanage.com and fmapi.net.

Camera

With the camera out on foot, W walks where the player and the camera face, and the mouse turns the player (the selfie camera too).

Config.Camera = { sprint = false, modeKey = 'F7' }

Menu: Device → Media → Camera.

Live Streams

Apps on the phone (such as Leakd and Glitch) can let players go live with the phone's camera. The video goes through your server to every viewer, so each viewer costs your server upload. A viewer counts as the video bitrate sent as base64 (4/3 of it) plus a tenth for sound and events: kbps × 4/3 × 1.1, about 1.47 times the bitrate. At the default 500 kbps that is about 0.73 Mbps a viewer, so 25 viewers count as about 18 Mbps. A stream that really sends more than that counts at what it sends.

Config.Streams = { enabled = true, maxViewers = 25, maxStreams = 4, kbps = 500, fps = 20, egressMbps = 40, maxMinutes = 60 }

Menu: Device → Media → Live streams. Admins can list and end streams with /phone streams and /phone endstream (see Admin).

Evidence

Everything police do with phones. Every check runs on the server. See Features → Police and Evidence.

A job row is { job = 'name', rank = number }: that job at that grade or higher.

Config.Evidence = {
    jobs = { { job = 'police', rank = 0 } },        -- who is police here
    authorizers = { { job = 'police', rank = 3 } }, -- who may issue search authorizations
    requireDuty = true,
    authorization = 'builtin',      -- 'builtin' | 'none' | 'hook'
    maxAuthorizationHours = 72,
    extractionSeconds = 60,
    requireStation = false,
    stations = {},                  -- { label, coords = vector3, radius }
    recoveryDays = 7,
    carrierDays = 30,
    traceCooldown = 120,
    traceRadius = 150.0,
    backends = { { name = 'oxide-police', enabled = true } },
    darkChatRecovery = 0,
}

A station written in the file looks like this:

stations = {
    { label = 'Mission Row Lab', coords = vector3(0.0, 0.0, 0.0), radius = 1.5 },   -- use your own position
},

Menu: Police → Evidence. Use the job names exactly as your framework spells them. Always give a station a Reach (radius).

Apps

The phone's own apps.

Config.Apps = {
    notes = { max = 100 },
    maps = { maxPlaces = 50 }, -- saved places (Home, Work, favourites, parked car) per phone
    darkchat = { enabled = true, perMinute = 15, maxRooms = 20 },
    feed = {
        enabled = true,
        perMinute = 3,
        maxLength = 280,
        postsPerHour = 30,   -- posts one number may make in an hour
        editMinutes = 15,    -- how long a post can be edited (0 turns editing off)
        trendHours = 24,     -- the hours trending hashtags are counted over
    },
    bank = {
        enabled = true,
        maxTransfer = 50000,        -- largest single transfer
        dailyLimit = 100000,        -- most one character sends in 24 hours
        perMinute = 3,
        requestsPerDay = 30,        -- payment requests one character may send in 24 hours
        requestHours = 24,          -- how long a payment request can be paid
    },
    gigs = { enabled = true }, -- the Oxide gig jobs that run here; off keeps their updates as texts
}

Menu: Screen → Apps.

Emergency Numbers

Config.Emergency = {
    enabled = true,
    numbers = {
        { number = '911', channel = '911', jobs = { 'police', 'ambulance' } },
        { number = '311', channel = '311', jobs = { 'police' } },
    },
}

Menu: Police → Emergency. Up to 10 numbers. See Features → Emergency Numbers for where a call goes.

Signal

Config.Signal = {
    indoorsNoSignal = false,
}

Menu: World → Signal → Signal (No signal indoors).

No-Signal Areas

Config.DeadZones = {}

Menu: World → Signal → No-signal areas. Draw each area in the world:

Redraw in the world reshapes an existing area. Each area needs 3 to 64 points, and you can have up to 100 areas. Drawing needs an o-link with in-world placement; with an older one the menu says so.

Store

Config.Store = {
    enabled = true,
    preinstalled = {}, -- e.g. { 'phone_darkchat', 'phone_feed' }
    simulateInstalls = true,
    installSpeed = 1,
    defaultAppSize = 50,
}

Menu: Screen → Home & Apps → Store.

How a download behaves. Tapping Get turns the button into a ring (tap it to cancel) and puts the app's icon on the next free spot of the home screen, dimmed, with a progress pie. Its label reads Waiting…, Loading…, then Installing…; then the icon brightens. Tapping the icon pauses or resumes the download (Paused); holding it offers Cancel Download. The app cannot open, notify or show widgets until it is installed.

• Time: the app's size divided by the download speed, with a little random variation, plus about a second before it starts and one to four seconds to install. Most apps take 5 to 20 seconds.
• Signal: weak signal slows the download. No signal, Airplane Mode or a phone that is off or flat pauses it on Waiting… until the signal returns.
• Kept by the server: closing the phone, logging out or restarting the resource never loses a download. A phone nobody is holding finishes on time in the background, and the app is there the next time it is opened.
• Not for every app: built-in apps and preinstalled apps are always there and never download. Removing an app is still instant.

Default Look

How every phone looks until its owner picks something else in Settings → Appearance on the phone. A player's own choice always wins. A player who taps Use server default goes back to these values.

Config.Appearance = {
    mode = 'dark',
    accent = 'blue',
    glass = 0.5,
}

Menu: Screen → Home & Apps → Default Look. A change reaches each phone the next time it is opened.

With Oxide HUD running, the card that rises while the phone is put away keeps the phone's own colours: there is no setting to give it Oxide HUD's accent colour. See Features → With Oxide HUD.

Home Screen

Config.Home = {
    dockSize = 4,
    maxPages = 4,
    wallpapers = {}, -- { id = 'skyline', label = 'Skyline', url = 'skyline.jpg' }
    wallpaperLinks = {}, -- e.g. { 'images.example.com', 'https://cdn.example.com/wallpapers/' }
}

A link is accepted only when it is an https:// address ending in .png, .jpg, .jpeg or .webp, with nothing after it (no ? or #), at most 512 characters, on an approved site. The phone checks this when the player adds the link and the server checks it again on every save; a site you later remove sends those phones back to the default wallpaper. The image loads from that site in the player's game, so approve only sites you trust.

Menu: Screen → Home & Apps → Home screen. Lowering a limit trims existing home screens to fit. See Installation → Custom Wallpapers.

Notifications

Config.Notifications = {
    bannerDuration = 4000, -- ms a banner stays on screen
    sound = { enabled = true, volume = 0.5 },
    stored = 100,          -- notifications kept per phone
}

Menu: Screen → Notifications. Players can also mute apps, turn banners or sound off, or use Do Not Disturb in their phone's Settings app.

App Start Timeout

Config.AppReadyTimeout = 8000

Menu: Screen → Home & Apps, on the Advanced tab (App start timeout).

Held Phone

The phone in the character's hand while the phone is open. The phone ships its own model in four colours (see Assets → Phone Models). The colour belongs to the phone, not the player: a phone keeps its colour for good, and everyone nearby sees it.

Config.Prop = {
    colour = 'random',
    itemColours = {},
    customModel = '',
    bone = 28422,
    offset = vector3(0.0, 0.0, 0.0),
    rotation = vector3(0.0, 0.0, 0.0),
}

Menu: Screen → Appearance (Held phone). Colour per phone item is a list: press Add for each row.

The bundled phone sits in the hand with no offset and no rotation, in every pose. Leave Offset and Rotation at zero unless you set Other model to a model that needs them.

Sell phones in colours (optional):

Phones made from items with no row use Colour.

Config.ModelHints lists the models the phone streams itself, so a warning about one of them says the install is incomplete. It is not in the menu; leave it as it is.

Model Replacements

Config.ModelSwaps = {} -- { { from = 'oxide_phone_black', to = 'your_model' } }

Menu: Advanced → Compatibility → Model replacements. When a model can't load, the phone warns in the console, tells online admins, and skips it. Add a row using the model name exactly as the warning shows it.

Timers

How often the server checks phones.

Config.Session = {
    watchdogSeconds = 5,
    scanSeconds = 15,
}

Menu: Advanced → Advanced, on the Advanced tab (Timers).

Setting Added by o-link: Map Mode

o-link adds one setting of its own to the phone's menu, for the Maps app. It is not in shared/config.lua.

Menu: Device → General (Map mode). Admins can also set it with oxide-phone:mapmode (see Admin).

App ID Reference

Use these IDs in Config.Store.preinstalled.

Apps from other resources have their own IDs; oxide-banking's app is banking.

Next Steps