Client exports
Custom apps
Client exports that register an app, talk to its page and control its icon.
The full guide to building an app, including the page side, is in Custom apps.
#AddCustomApp
Adds an app to this player's phone. The app is a web page of your resource, shown in an iframe.
lua---@class CustomAppDefinition
---@field identifier string app id: letters, digits, `_` and `-`, at most 40 characters (`appId` and `id` are accepted too)
---@field name string name under the icon, up to 40 characters (`label` is accepted too)
---@field ui string path of the page: '<resource>/<file>' or a path inside your resource
---@field icon? string path or link of the icon
---@field description? string up to 500 characters, shown in the App Store
---@field developer? string up to 60 characters; your resource name by default
---@field defaultApp? boolean true: already installed. false: the player installs it from the App Store (`defaultInstalled` is accepted too)
---@field size? number size shown in the App Store
---@field images? string[] screenshots for the App Store
---@field price? number App Store price, 0 or more
---@field category? string App Store category, 'other' by default
---@field jobs? string[] jobs that may use the app
---@field landscape? boolean the app supports landscape
---@field keepOpen? boolean
---@field fixBlur? boolean
---@param def CustomAppDefinition
---@return boolean ok
---@return string|nil err
exports['fx-phone']:AddCustomApp(def)
lualocal ok, err = exports['fx-phone']:AddCustomApp({
identifier = 'garage', name = 'Garage', ui = 'my-garage/html/index.html', icon = 'my-garage/html/icon.png', defaultApp = true,
})
- Errors:
invalid(not a table),invalid_id,invalid_ui,reserved_id(the id belongs to a built-in app). - Calling it again with the same id replaces the app.
- The app is removed when your resource stops.
- Register again when the phone reloads: listen to the client event
fx-phone:client:phoneLoaded. See Client events.
#RemoveCustomApp
Removes an app you added.
lua---@param id string
---@return boolean ok
---@return string|nil err 'not_found'
exports['fx-phone']:RemoveCustomApp(id)
luaexports['fx-phone']:RemoveCustomApp('garage')
#SendCustomAppMessage
Sends data to your app's page.
Also available as: SendCustomNUIMessage
lua---@param id string
---@param data any
---@return boolean ok
---@return string|nil err 'not_found' when the app is not registered
exports['fx-phone']:SendCustomAppMessage(id, data)
luaexports['fx-phone']:SendCustomAppMessage('garage', { action = 'vehicles', list = vehicles })
- The page receives it with
window.addEventListener('message', ...). See App API.
#SetInputFocus
Tells the phone that a text field in your app has focus, so typing does not move the character.
lua---@param focused boolean
exports['fx-phone']:SetInputFocus(focused)
luaexports['fx-phone']:SetInputFocus(true)
- Only matters with
Config.WalkWhileOpen = true.
#ToggleFocusKeepInput
Sets whether game input stays active while the phone has focus. It is SetInputFocus with the opposite value.
lua---@param keepInput? boolean default true
exports['fx-phone']:ToggleFocusKeepInput(keepInput)
luaexports['fx-phone']:ToggleFocusKeepInput(false)
#SetAppBadge
Sets the number badge on an app icon.
lua---@param id string
---@param count number 0 to 999; 0 clears the badge
---@return boolean ok
exports['fx-phone']:SetAppBadge(id, count)
luaexports['fx-phone']:SetAppBadge('garage', 2)
#SetAppInstalled
Installs or uninstalls an app for this player.
lua---@param id string
---@param installed boolean
---@return boolean ok false only when `id` is not a string
exports['fx-phone']:SetAppInstalled(id, installed)
luaexports['fx-phone']:SetAppInstalled('garage', true)
- The change is sent to the server in the background;
truemeans the request was sent, not that it was applied.
#SetAppHidden
Hides an app icon on the home screen without uninstalling it.
lua---@param id string
---@param isHidden boolean
---@return boolean ok
exports['fx-phone']:SetAppHidden(id, isHidden)
luaexports['fx-phone']:SetAppHidden('garage', true)