📱SMARTPHONE

Overview

Forge Phone replaces legacy phone scripts with a cohesive mobile experience:

• FORGE OS — lock screen, home screen, dock, control center, notifications, app store, themes and wallpapers.

• Real-time communication — SMS-style messages, group chats, voice calls through pma-voice, and optional WebRTC video calls.

• Life simulation — camera with cloud upload, gallery, email, classified ads, dating, social feeds, and streaming.

• Economy hooks — bank transfers, invoices, and a ByteMe mobile data system that gates online actions.

• Underworld & law enforcement — a retro burner phone excluded from wiretap, and a police tablet for surveillance dossiers.

Open the phone with the configured key (default M), the /phone command, or by using the phone item from inventory.

---

Features

Feature	Description
Voice calls	Outgoing/incoming calls with history, contact integration, and pma-voice routing
Video calls	WebRTC peer video with STUN/TURN support and in-game cell camera
Messages	Direct chats with read state, media, and contact requests
Contacts	Full address book synced to the server
Camera & Gallery	In-game photos uploaded to FiveManage, stored per character
App Store	Install/uninstall downloadable apps defined in Config.Apps
ByteMe (InetMax)	Mobile data balance consumed by calls, posts, transfers, and messages
Bank (Wallet)	Balance, transfers, and bill payments with framework or ds_banking
Mail	Inbox for receipts, ads, and server announcements
Services	Ticket threads to police, EMS, taxi, businesses, and more
Social apps	Bleeter, Insta, WhatsUP groups, Spark dating, LifeInvader ads
Play TV	Video streaming surface inside the phone
Burner phone	Separate disposable device with its own number pool
Police wiretap	Tablet UI for GPS, message/call history, live intercept, and dossiers
Signal zones	Optional dead zones where sending/calling is blocked
i18n	English and Spanish locales in the phone UI
Themes	Accent color, wallpaper, and OS personalization in Settings

---

Apps

Pre-installed (System)

These apps ship on every phone and cannot be uninstalled:

ID	Display name	Purpose
phone	Phone	Dialer, recent calls, contact requests
messages	Messages	Direct messaging
contacts	Contacts	Address book
camera	Camera	Take photos in-world
settings	Settings	Theme, wallpaper, notifications, privacy
appstore	App Store	Browse and manage downloadable apps
gallery	Photos	Photo library

Downloadable (App Store)

Users install these from the App Store. Only IDs listed in Config.Apps.Downloadable are available:

ID	Display name	Category	Description
wallet	Bank	Finance	Balance, transfers, bills
email	Mail	Productivity	Character inbox
services	Services	Utilities	Contact jobs and emergency services
loops	Bleeter	Social	Twitter-style posts and comments
ads	Ads	Utilities	Classified listings with photos
inetmax	ByteMe	Utilities	Top up and monitor mobile data
playtv	Play TV	Entertainment	Stream videos on the go
lovy	Spark	Social	Dating / swipe profiles
snapmatic	Insta	Social	Photo feed, likes, comments
whatsup	WhatsUP	Social	Group chat rooms

To change which apps are system vs downloadable, edit Config.Apps in config/config.lua.

---

Requirements

Start dependencies before forge-phone:

ensure ox_lib
ensure oxmysql
ensure screenshot-basic
ensure pma-voice
ensure forge-phone

Dependency	Role
ox_lib	Callbacks, UI helpers, shared utilities
oxmysql	Database queries and migrations
screenshot-basic	Camera capture pipeline
pma-voice	Voice calls and wiretap audio bridge

Optional integrations

• FiveManage — photo upload API (see Camera & Photo Upload)

• ds_banking — external banking when Config.Banking.Resource = 'auto'

• MugShotBase64 — live mugshots on the wiretap tablet

• interact-sound — ring tones (customize in config/open_functions.lua)

If your server uses another voice resource, override ForgePhone.JoinVoiceCall, ForgePhone.LeaveVoiceCall, and the wiretap voice helpers in config/open_functions.lua.

---

Installation

1. Add the resource

Place the folder in your resources directory as forge-phone and ensure it in server.cfg after the dependencies.

2. Set your framework

In config/config.lua:

Config.Core = "QBX" -- "QB", "QBX" or "ESX"

3. Configure item names

Config.PhoneItem = 'phone'
Config.Burner.Item = 'burner_phone'

4. Register inventory items

Add the phone and burner items to your inventory system (see Inventory Items).

5. Database

On first start, Forge Phone creates and migrates its database tables automatically.

If your host blocks automatic DDL, import forge-phone.sql manually before starting the resource.

6. FiveManage API key

Add your media API key to server.cfg before the resource starts:

set FIVEMANAGE_MEDIA_API_KEY "your_fivemanage_media_api_key"

Never expose the API key outside server.cfg (no public configs, screenshots, or shared paste links).

7. Optional bridges

Adjust hooks in:

• config/open_functions.lua — sounds, voice, mugshots

• config/bridge_client.lua — client framework bridge

• config/bridge_server.lua — server framework bridge, money, jobs, items

---

Inventory Items

The normal phone opens with forge-phone:client:open. The burner opens with forge-phone:client:openBurner.

Use non-consumable items. The script verifies the player still has the item before opening and while burner call state is active.

ox_inventory

Add to ox_inventory/data/items.lua:

['phone'] = {
    label = 'Phone',
    weight = 300,
    stack = false,
    close = true,
    consume = 0,
    client = {
        event = 'forge-phone:client:open',
    },
    description = 'Forge smartphone',
},

['burner_phone'] = {
    label = 'Burner Phone',
    weight = 250,
    stack = false,
    close = true,
    consume = 0,
    client = {
        event = 'forge-phone:client:openBurner',
    },
    description = 'Disposable phone',
},

QBCore / qb-inventory

Add to qb-core/shared/items.lua:

['phone'] = {
    name = 'phone',
    label = 'Phone',
    weight = 300,
    type = 'item',
    image = 'phone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'Forge smartphone',
},

['burner_phone'] = {
    name = 'burner_phone',
    label = 'Burner Phone',
    weight = 250,
    type = 'item',
    image = 'burner_phone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'Disposable phone',
},

Register usable callbacks server-side (after qb-core loads):

local QBCore = exports['qb-core']:GetCoreObject()

QBCore.Functions.CreateUseableItem('phone', function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player or not Player.Functions.GetItemByName(item.name) then return end
    TriggerClientEvent('forge-phone:client:open', source)
end)

QBCore.Functions.CreateUseableItem('burner_phone', function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player or not Player.Functions.GetItemByName(item.name) then return end
    TriggerClientEvent('forge-phone:client:openBurner', source)
end)

QBX / qbx_core

If you use QBX with ox_inventory, use the ox_inventory definitions above.

Otherwise:

exports.qbx_core:CreateUseableItem('phone', function(source)
    TriggerClientEvent('forge-phone:client:open', source)
end)

exports.qbx_core:CreateUseableItem('burner_phone', function(source)
    TriggerClientEvent('forge-phone:client:openBurner', source)
end)

ESX

SQL for the legacy items table:

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('phone', 'Phone', 300, 0, 1),
    ('burner_phone', 'Burner Phone', 250, 0, 1)
ON DUPLICATE KEY UPDATE
    `label` = VALUES(`label`),
    `weight` = VALUES(`weight`);

If your table only has name, label, and weight, remove rare and can_remove.

Server callbacks:

ESX.RegisterUsableItem('phone', function(source)
    TriggerClientEvent('forge-phone:client:open', source)
end)

ESX.RegisterUsableItem('burner_phone', function(source)
    TriggerClientEvent('forge-phone:client:openBurner', source)
end)

qs-inventory

Add to qs-inventory/shared/items.lua:

['phone'] = {
    ['name'] = 'phone',
    ['label'] = 'Phone',
    ['weight'] = 300,
    ['type'] = 'item',
    ['image'] = 'phone.png',
    ['unique'] = true,
    ['useable'] = true,
    ['shouldClose'] = true,
    ['combinable'] = nil,
    ['description'] = 'Forge smartphone',
},

['burner_phone'] = {
    ['name'] = 'burner_phone',
    ['label'] = 'Burner Phone',
    ['weight'] = 250,
    ['type'] = 'item',
    ['image'] = 'burner_phone.png',
    ['unique'] = true,
    ['useable'] = true,
    ['shouldClose'] = true,
    ['combinable'] = nil,
    ['description'] = 'Disposable phone',
},

QS setups based on QBCore still need the CreateUseableItem callbacks unless your QS version binds its own client events.

---

Configuration

All customization is done through these files:

config/config.lua          — core settings, apps, wiretap, video, signal, services
config/vehicles.lua        — vehicle-related helpers
config/open_functions.lua  — voice, sounds, mugshots (client hooks)
config/bridge_client.lua   — framework client bridge
config/bridge_server.lua   — framework server bridge
config/logs_server.lua     — server logging hooks

Essential settings

Config.Core = "QBX"
Config.OpenPhone = 'M'
Config.PhoneItem = 'phone'
Config.AllowWalkingWhilePhoneOpen = true

Config.Burner.Enabled = true
Config.Burner.Item = 'burner_phone'
Config.Burner.Command = 'burnerphone'

App catalog

Config.Apps = {
    System = {
        'phone', 'messages', 'contacts', 'camera',
        'settings', 'appstore', 'gallery',
    },
    Downloadable = {
        'email', 'wallet', 'services', 'loops', 'ads',
        'inetmax', 'playtv', 'lovy', 'snapmatic', 'whatsup',
    },
}

Only apps listed in Config.Apps.System or Config.Apps.Downloadable can be installed or removed.

Call settings

Config.RepeatTimeout = 3000   -- ms between ring tones
Config.CallRepeats = 5        -- rings before missed call

Notification texts

Customize player-facing strings in Config.Texts and per-feature Texts tables (burner, wiretap, etc.).

---

Burner Phone

The burner is a separate disposable device with a retro UI and its own number table. It is intentionally excluded from police wiretap and tracking.

Setting	Default	Notes
Config.Burner.Enabled	true	Master switch
Config.Burner.Item	burner_phone	Inventory item
Config.Burner.Command	burnerphone	Opens without item if enabled
Config.Burner.AllowIncomingCalls	true	Incoming burner calls
Config.Burner.NumberMin/Max	1000–9999	Short number pool

Features toggled under Config.Burner.Features: outgoing calls, contacts, settings.

Behaviour highlights

• Cannot open the main phone and burner at the same time during active calls.

• Uses prop model npds_oldphone_base (see Props).

• Numbers are stored separately from the main phone profile.

---

Police Wiretap Tablet

Judicial surveillance tool for configured police jobs. Open with /poltablet (configurable).

Config.Wiretap = {
    Enabled = true,
    Command = 'poltablet',
    Jobs = {
        ['police'] = 0,
        ['sheriff'] = 0,
    },
    MaxSessionsPerOfficer = 1,
    LocationUpdateIntervalMs = 2000,
    JoinVoiceOnActiveCall = true,
    Features = {
        HistoricalMessages = true,
        HistoricalCalls = true,
        HistoricalSocialActivity = true,
        LiveMessages = true,
        LiveCallAudio = true,
        LocationTracking = true,
        PortraitCapture = true,
    },
}

What officers can do

• Target dossiers — save suspects with labels (suspect, witness, victim, etc.), notes, and display names.

• GPS tracking — live map with periodic position updates from the target client.

• Message history — SMS and service threads linked to the target number.

• Call history — past call metadata.

• Live intercept — real-time messages while a wiretap session is active.

• Live call audio — when enabled, the officer joins the target's pma-voice call in listen-only mode.

• Portrait — mugshot from DB avatar, optional MugShotBase64 resource, or native capture.

Limits

• Burner phones are never wiretappable.

• MaxSessionsPerOfficer prevents abuse.

• History rows are capped by Config.Wiretap.HistoryLimits.

Preset labels: suspect, witness, victim, person_of_interest, accomplice, informant, other.

---

Video Calls

WebRTC video calls run between two players in an active phone call.

Config.VideoCall = {
    Enabled = true,
    STUNServers = {
        "stun:stun1.l.google.com:19302",
        "stun:stun2.l.google.com:19302",
    },
    TURNServers = {}, -- add your TURN credentials for strict NAT
    InetMaxUsage = math.random(300000, 800000),
}

Requirements

• Config.VideoCall.Enabled = true

• Both players need sufficient ByteMe data when InetMax is enabled.

• pma-voice handles call audio; video uses WebRTC with the STUN/TURN settings below.

For production servers behind strict firewalls, configure TURN servers in TURNServers. Google STUN alone is enough for many home networks but not all datacenter setups.

---

ByteMe — Mobile Data

ByteMe (inetmax app) is Forge Phone's mobile data economy. When Config.App.InetMax.IsUseInetMax = true, online actions consume KB from the character balance.

Top-up

Config.App.InetMax.TopupRate = {
    InKB = 1000000,  -- 1 GB per unit
    Price = 100,     -- price per unit
}
Config.App.InetMax.SocietySeller = "government"

Usage examples (randomized ranges in KB)

Action	Config key
Send message	MessageSend
Bleeter post / comment	LoopsPostTweet, LoopsPostComment
Insta post / comment	SnapmaticPost, SnapmaticComment
Ads post	AdsPost
Voice call	PhoneCall
Video call	Config.VideoCall.InetMaxUsage
Bank transfer	BankTransfer
Service message	ServicesMessage

If the balance is too low, players see Config.MsgNotEnoughInternetData and the action is blocked.

---

Camera & Photo Upload

Photos are captured through screenshot-basic and uploaded to FiveManage:

Config.PhotoUpload = {
    provider = 'fivemanage',
    endpoint = 'https://api.fivemanage.com/api/v3/file/base64',
    timeout = 10000,
    encoding = 'webp',
    quality = 0.85,
    path = 'forge-phone/photos',
}

server.cfg

set FIVEMANAGE_MEDIA_API_KEY "your_fivemanage_media_api_key"

Saved URLs are stored in the gallery and can be used in Bleeter, Insta, Ads, Spark, and profile avatars.

---

Banking & Wallet

Config.Banking = {
    Resource = 'auto', -- auto, framework, ds_banking
    AutoDetect = { 'ds_banking' },
}

Mode	Behaviour
auto	Tries listed external banks, falls back to framework account
framework	Uses QB/QBX/ESX bank balance only
ds_banking	Forces ds_banking integration

The Wallet app supports transfers, balance checks, and invoice payments. Top-ups for ByteMe credit the configured society account.

Admin diagnostic

/fpbankdiag prints banking diagnostics but requires ACE permission forgephone.bankdiag (or generic command ace).

---

Signal Zones

Optional coverage simulation. Disabled by default.

Config.Signal = {
    IsUse = false,
    DefaultSignalZones = "FULL_SIGNAL",
    Zones = {
        ["FULL_SIGNAL"] = {
            CenterCoords = vec3(49.58, -1560.84, 29.38),
            Radius = 3,
            ChanceSignal = 1.0,
        },
        -- add more zones with ChanceSignal 0.0 – 1.0
    },
}

When IsUse = true, players inside low-signal zones cannot send messages or place calls. Message: Config.MsgSignalZone ("No Signal").

---

Services App

Pre-configured service desks in Config.Services. Each entry maps a job name to a ticket channel:

Key	Job	Type
goverment	goverment	General
police	police	General
ambulance	ambulance	Health
realestate	realestate	Property
taxi	taxi	Transport
burgershot	burgershot	Food
kfc	kfc	Food

Add or rename entries to match your server's jobs. minGrade controls which job grade can respond to tickets.

---

Props & Stream Files

Phone and burner props are streamed from stream/:

stream/npds_phone_base.ydr      — main smartphone prop
stream/npds_oldphone_base.ydr     — burner phone prop
stream/npds_phone_prop.ytyp     — archetype metadata

Manifest entry:

data_file "DLC_ITYP_REQUEST" "stream/npds_phone_prop.ytyp"

Device	Model
Main phone	npds_phone_base
Burner phone	npds_oldphone_base

If a prop appears grey or untextured, the drawable loaded but the texture dictionary did not. Add matching .ytd files from the NPDS prop package to stream/ if included, restart the resource, and clear client cache if needed.

These props are created by Nukepug Designs — see Special Thanks.

---

Debug & Troubleshooting

Enable debug logs

Config.Debug = false

Config.DebugScopes = {
    all = true,
    bridge = true,
    camera = true,
    database = true,
    phone = true,
    props = true,
    signal = true,
    web = true,
    wiretap = true,
}

Set Config.Debug = true. Use all = false and enable individual scopes to reduce console noise.

Common issues

Symptom	Check
Phone does not open	Item registered, Config.PhoneItem matches, player has item
No photos / gallery empty	FIVEMANAGE_MEDIA_API_KEY in server.cfg, screenshot-basic running
No voice in calls	pma-voice started, ForgePhone.JoinVoiceCall not overridden incorrectly
Video call black screen	TURN servers, firewall, Config.VideoCall.Enabled
Wiretap no GPS	Target online, tap session active, LocationTracking enabled
Database errors	oxmysql connection, run forge-phone.sql manually if DDL blocked
Grey phone prop	Missing .ytd textures in stream/

Commands

Command	Access	Purpose
/phone	All	Open phone (if item checks pass)
/burnerphone	All	Open burner (if enabled)
/poltablet	Wiretap jobs	Open police surveillance tablet
/fpbankdiag	ACE forgephone.bankdiag	Banking diagnostics

---

Special Thanks

Forge Phone uses community-made props for the in-hand phone models. Huge thanks to Nukepug Designs (NukePugs) for creating and sharing high-quality props and scripts for the FiveM community.

	Link
Discord	Nukepug Design's
GitHub	NukepugDesigns

Nukepug Designs publishes prop packs, MLOs, minigames, and more for roleplay servers. If you use Forge Phone props in trailers or showcases, consider crediting Nukepug Designs and supporting their work.

Props used in this resource

• npds_phone_base — main smartphone

• npds_oldphone_base — burner phone

• npds_phone_prop.ytyp — prop metadata

---

License & Support

Forge Phone is distributed by CodeForge. Refer to your Tebex or purchase page for license terms, updates, and official support channels.

For configuration questions, start with this document and the files under config/. Enable scoped debug logging before opening support tickets so staff can diagnose issues quickly.