Configuration Reference

Every setting in oxide-tablet, what it does in game, and its default value. Start with How Settings Work — the tablet saves its settings in your database, so editing the config file does not always do what you expect.

How Settings Work

oxide-tablet keeps its settings in your database (the MySQL database your server already uses), not only in the config file. This lets admins change settings in game with /tablet settings. It also changes how the config file behaves, so read this section before you edit anything.

The Short Version

• The first time oxide-tablet 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 /tablet 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-tablet 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.Notifications, that one option is added and your other notification settings stay as they are.
• Lists are never merged. Config.Items, Config.Home.wallpapers, Config.Store.preinstalled, Config.ModelSwaps, Config.MapLocations and Config.MapBlipOverrides are saved as a whole. After the first start, the whole list comes from the database.
• The reset arrow in the in-game menu puts a setting back to the value in shared/config.lua (see below).

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

Changing Settings in Game

The reset arrow next to a setting puts it back to the value shared/config.lua had the last time the resource started. The reset is saved immediately; you do not need to press Save. For settings that contain several options (such as Home screen, which holds dock size, max pages and the wallpaper list), the reset puts back all of them together.

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.

To apply one setting from the file:

To load every setting from the file again:

DELETE FROM oxide_settings WHERE resource = 'oxide-tablet';

When Changes Take Effect

Where each setting is in the /tablet settings menu and when a saved change starts working:

Settings Not in the Menu

Config.SettingsCommand is the only setting the in-game menu does not show. It is still copied into the database on the first start, so editing it in shared/config.lua afterwards does nothing, and it has no reset arrow.

To change it after the first start:

DELETE FROM oxide_settings WHERE resource = 'oxide-tablet' AND setting_key = 'SettingsCommand';

Config File: shared/config.lua

Every setting below lives in shared/config.lua. Remember that after the first start, the /tablet settings menu is the place to change them (see How Settings Work). The ranges listed are what the in-game menu accepts.

General

Config.Enabled = true
Config.Debug = false

Config.OpenKey = ''              -- no default key; players bind their own
Config.EscapeBehavior = 'home'   -- 'home' or 'close'
Config.AppReadyTimeout = 8000    -- 8 seconds

Config.SettingsCommand = '/tablet settings'

Tablet Items

These settings decide which inventory items open the tablet and which apps each item shows.

Config.RequireItem = true

Config.Items = {
    { item = 'tablet', apps = {} },
}

Each item must exist in your inventory's item list before it can be used. See Installation → Framework Setup for adding the tablet item to your inventory.

Normal Tablets and Curated Tablets

The apps list decides what kind of tablet an item is.

Rules for curated tablets:

• Listed apps still follow their own job and gang rules. If an app only shows for police officers, a civilian holding the curated tablet sees only Settings.
• An app ID for a resource that is not installed (or not started) simply does not appear.
• You do not need to list tablet_settings: Settings is on every tablet.
• Do not list app_store. The store would open, but every app in it would be locked.
• When a player carries several tablet items, using an item opens that item. The keybind and /tablet open open the tablet in the lowest inventory slot, and that item's row decides the apps.

Example: A Work Tablet That Only Runs One App

Config.Items = {
    { item = 'tablet', apps = {} },                    -- normal tablet with the App Store
    { item = 'work_tablet', apps = { 'their_app' } },  -- curated: only that one app
}

Replace their_app with the app ID from the resource that adds the app, and work_tablet with your own item. The app only exists while that resource is running and supports the tablet.

Devices

Each tablet item gets its own 15-digit IMEI (serial number) the first time it is used. See Features → Tablet Devices and IMEI Numbers for how devices work.

Config.Device = {
    stampDescription = true,   -- show "IMEI 35..." in the item tooltip
}

Battery

A tablet with an IMEI has a battery. It loses charge while the tablet is out, and gets it back while the tablet is put away. At 0% the tablet puts itself away and won't open again until it has recharged. The level belongs to the tablet item, so it goes with the item when it changes hands.

Tablets without an IMEI have no battery and never run out: the keybind with Require an item off, a tablet another resource opened for its own app, and inventories that can't save an IMEI on items.

Config.Battery = {
    enabled = true,
    drainPerMinute = 0.5,      -- % lost per minute the tablet is out
    rechargePerMinute = 1.5,   -- % gained per minute it is put away; 0 = never
}

Recharging is worked out when the tablet is next opened, from how long it was away. It keeps counting while the player is offline and while the server is off. A flat tablet stays shut until it holds a whole percent again, which takes about 40 seconds at the factory rate.

Hold Animation

While the tablet is open, the player holds a tablet prop with an animation. Other players see it.

Config.HoldAnimation = {
    enabled = true,
    dict = 'amb@code_human_in_bus_passenger_idles@female@tablet@base',
    clip = 'base',
    flag = 49,                                -- loop + upper body + allow movement
    prop = {
        model = 'prop_cs_tablet',
        bone = 60309,
        offset = vec3(0.03, 0.002, 0.0),      -- metres from the bone
        rotation = vec3(10.0, 160.0, 0.0),    -- degrees
    },
}

In the in-game menu, Offset and Rotation each have three boxes: X, Y and Z.

Home Screen

These settings set limits on the home screen and add picture wallpapers. The layouts themselves belong to each tablet (or character), and players edit them in game.

Config.Home = {
    dockSize = 6,
    maxPages = 5,
    wallpapers = {},   -- { id = 'skyline', label = 'Skyline', url = 'skyline.jpg' }
}

• Values above the limits are treated as the limit (a dockSize of 10 acts as 6).
• Lowering dockSize or maxPages does not delete anyone's apps. Apps that no longer fit move into the App Library, under Not on home screen, and drop back onto a page the next time the player edits their home screen. Widgets on a removed page are taken off and can be added again.

Adding a Wallpaper Image

Things to know:

• Only https:// web addresses work. A row with an http:// address is left out of the picker.
• A row with an unusable image address is left out of the picker. With Config.Debug on, a console line names it. A row with a missing or invalid id is left out silently.
• Keep the id the same once players have picked the image. Changing the file or web address of a row is fine: players keep the wallpaper and see the new picture.
• If you remove a row or change its id, players who picked it go back to the default wallpaper.
• Players can only choose from your list and the presets. They cannot enter their own links.

App Store

These settings control how apps get onto tablets. See Features → The App Store for what players see.

Config.Store = {
    enabled = true,      -- false = no store; every allowed app is installed
    preinstalled = {},   -- for example { 'tablet_map' }
}

• Preinstalled apps still follow their app's rules. An app limited to police only shows for police, even when preinstalled.
• Curated tablets ignore both settings. An item with an apps list shows exactly that list (see Tablet Items).
• Turning the store off keeps players' installs. They come back if you turn the store on again.
• Unknown IDs do nothing. An ID for a resource that is not installed is ignored.
• App IDs are listed in App ID Reference.

How Items and the App Store Work Together

Maps

These settings control the built-in Maps app. See Maps App for full details on how Maps, locations and blip overrides work. Adding locations in game is easiest: the menu has a placement button that lets you pick the spot in the world instead of typing coordinates.

Config.MapEnabled = true
Config.MapAutoBlips = true
Config.MapMode = 'inherit'    -- 'inherit', 'combined', 'separate' or 'disabled'
Config.MapLocations = {}
Config.MapBlipOverrides = {}

Admins can also change the map mode with the oxide-tablet:mapmode command. See Admin Tools.

Location Rows (Config.MapLocations)

Override Rows (Config.MapBlipOverrides)

Create these with the Detected blip overrides tool in /tablet settings, which fills in the matching fields for you.

Allowed Icons and Colours

Notifications

These settings control the notifications apps post to the tablet. Players fine-tune what they receive in the Settings App; these are the server-wide switches and limits.

Config.Notifications = {
    enabled = true,
    maxStored = 100,        -- per player; oldest removed first
    toastDuration = 5000,   -- 5 seconds
    showWhenClosed = true,  -- bubble while the tablet is put away
    sound = { enabled = true, file = 'notification.mp3', volume = 0.5 },
}

Notifications are kept in each player's game only, never in the database. They are cleared when the player logs out or switches character.

Model Swaps

Some game builds are missing models that newer builds have. oxide-tablet loads one model: the tablet prop in the player's hand (Config.HoldAnimation.prop.model, which is prop_cs_tablet by default).

If a player's game cannot load that model:

• The tablet still opens, without the prop. Nothing freezes.
• The player's F8 console shows a warning naming the model.
• Online admins get a notification like: [oxide-tablet] model "prop_name" is not on this game build. Set a replacement in /tablet settings.
• Nothing is replaced automatically. You choose the replacement.

Config.ModelSwaps = {}
-- { from = 'prop_cs_tablet', to = 'prop_some_other_tablet' }

To add a replacement in game:

You can also change Config.HoldAnimation.prop.model directly instead of adding a swap. Both work.

App ID Reference

App IDs are the short names you put in Config.Items[n].apps and Config.Store.preinstalled.

Apps from other resources have their own IDs, set by those resources. Check that resource's documentation for its app ID.

Next Steps