Features

Phone shop

Phone shop counters, products, the 3D showroom and the player-run shop business.

Phone shops are counters in the world with a clerk NPC. A player walks up, talks to the clerk and buys a phone, a SIM card, an eSIM, a new number or a colour for their phone. With fx-phone-assets running, the clerk can also set a 3D phone on the counter for the player to turn around and dress with cases and accessories.

The shops can be run by players: one job owns them, employees serve customers for a commission, and the money goes to the job's account.

Everything is in Config.PhoneShop.

Part What it is
Shops Counter locations with an NPC, a blip and opening hours
Talk screen The conversation with the clerk and the product list
Products What is sold and at what price
Showroom The 3D phone on the counter (needs fx-phone-assets)
Business The shops as a player-run business (optional)

#How it works for the player

  1. The player walks to a shop. The clerk appears when they come within SpawnDistance metres.
  2. With ox_target running they target the clerk and pick Talk. Without it, a help text shows within 2 metres: press E.
  3. The camera moves in on the clerk, the HUD and the radar step aside, and the talk screen opens. The phone closes if it was open.
  4. The player picks a product and pays. The receipt shows what they got: the new number and ICCID for a SIM, the new colour for a case.
  5. Esc or Close leaves the counter.

Outside opening hours the clerk still talks, but says the shop is closed and sells nothing.

The server checks every purchase: the shop must be enabled and open, and the player must stand within 6 metres of the counter.

#Payment

Payment decides where the money comes from:

Value Result
'cash' Cash only
'bank' Bank only
'both' Cash if the player has enough cash, otherwise bank

With 'both' the whole price comes from one account; it is not split between cash and bank.

#Welcome gift for moved players

A player whose phone was moved over from another phone script with fxphone:migrate (see Migration) gets one purchase at a discount, set in Config.Migration.Gift (default 50 % off, valid 14 days from their first open after the move, MaxAmount = 0 for no cap on the amount).

  • At the counter's checkout the discount shows as its own line ("Welcome gift: -50%") and the total and the Pay button show the price after it. The receipt says how much was saved.
  • It applies to the products sold on the talk screen. Parts bought in the showroom cart (cases, accessories, letters from the accessory store, and a colour bought there) do not use it.
  • It comes after any discount an employee gives at the counter, and the price never goes below 0.
  • It is used up only when the purchase goes through. A purchase that fails (not enough money, full inventory, sold out, a SIM limit) leaves it unused.
  • It works once: the server holds it for the one purchase that is running, so two purchases at the same moment, or a relog, cannot use it twice. A purchase that asked for it after it was used is refused rather than charged the full price, and the checkout then shows the full price.
  • Who pays for it: the customer simply pays less. The sale is booked at the price paid, so with the business on the shop's account (and the employee's commission, which is a share of the price paid) receive less for that one sale. No money is added from anywhere to make up the difference.

#Products (Products)

lua{ kind = 'phone', item = 'phone', label = 'shop.products.phone', price = 750, enabled = true },
{ kind = 'case', variation = 'silver', label = 'shop.products.case', price = 120, enabled = true },
Field What it is
kind What the product does, see below
item Inventory item handed out, for the kinds that hand one out
variation For case: one of the 14 phone colours
label Locale key of the product name
price Base price
enabled false takes it off sale everywhere
Kind What the player gets Shown only when
phone The phone item. Up to 5 at a time An inventory is detected
sim A physical SIM registered to the buyer, with a new number Config.Sim.Enabled = true and an inventory
sim_prepaid A prepaid physical SIM with a new number, registered to nobody As sim, plus the shop has prepaid = true and Config.Sim.AllowUnregistered is not false
esim A registered eSIM. It switches on at once in a free SIM slot; refused only when both slots are taken Config.Sim.Enabled = true
reissue A new card for a lost registered SIM, same number. The old card stops working Config.Sim.Enabled = true and an inventory
number_change A new number for one SIM in the phone. With two SIMs in, the player picks which line. Refused for a registered SIM that belongs to someone else. With SIM cards off, a new number for the character Always
case Changes the colour of the player's phone (the frame on screen and the 3D phone in hand) Always, see CasesChangeVariation

The 14 colours are black, silver, white, light_gold, cosmic_orange, pink, lavender, purple, burgundy, deep_blue, mist_blue, glacier, sage and forest.

SIM rules (registered SIMs per character, who may reissue, the ID check) are those of SIM cards. A registered SIM is sold with the buyer's name on it; the clerk asks for ID first. A prepaid SIM needs no ID.

A purchase that fails after the money was taken (full inventory, SIM limit) is refunded.

#Shops (Shops)

luaShops = {
    legion = {
        name = 'FX Mobile Legion',
        coords = { x = 195.17, y = -933.77, z = 30.69, heading = 144.0 },
        npcModel = 's_f_y_shop_mid',
        npcScenario = 'WORLD_HUMAN_STAND_IMPATIENT',
        blip = true, blipSprite = 459, blipColor = 3,
        openFrom = 8, openTo = 22,
    },
    paleto = { ..., prepaid = true },
},

The config only seeds the shops. On start, every entry whose key (legion, paleto) is not in the database yet is added. From then on the database owns it: changing an entry in config.lua does nothing to a shop that already exists, and removing it does not delete it. Edit shops on the admin tablet instead. A new key in the config adds a new shop on the next start.

Field What it is
name Shop name, also the blip name
coords Where the clerk stands, with heading
npcModel Clerk model. The tablet only offers models from NpcModels
npcScenario What the clerk does while waiting: a scenario name or a key from NpcScenarios
blip, blipSprite, blipColor Map blip
openFrom, openTo Opening hours, whole hours 0 to 23. Leave both out (or make them equal) for always open. openFrom = 22, openTo = 6 runs past midnight
prepaid This shop sells prepaid SIMs

#Admin tablet, Shops section

Admins can add, edit and remove shops: name, position (the Here button takes the position you stand at), clerk, scenario, blip, hours, prepaid on or off, and per-shop prices and on/off for each product. The god role can switch every shop off and on at once, and teleport to a shop. Changes apply at once for every player.

#Blips and opening hours

The blip is a short-range blip named with the hours, for example "FX Mobile Legion 08:00-22:00". Outside opening hours it stays on the map, dimmed.

Hours = 'always' (the default) keeps every shop open round the clock; the hours below then only wait for the day it is changed.

Hours = 'game' follows the game clock that a time sync resource publishes (GlobalState.currentTime), or the server's real time when there is none; 'real' always uses the server's real time. The server decides whether a shop is open, and the blips show the same. With fx-3dmap running the shops are also shown on its map and follow its category switch: see Map integration.

#Talk screen

The clerk is a local NPC: each player's game places its own, nothing is networked. It is created within SpawnDistance metres and removed beyond DespawnDistance.

The camera sits between the player and the clerk, shifted so the clerk stands beside the panel. If the player stands close, the camera moves in and widens instead. The clerk's line types out beside their chest and their mouth moves while it does.

Hud.OnOpen and Hud.OnClose are functions run when the talk screen opens and closes. The shipped ones hide and show wais-hudv6 and fx-hud; a HUD that is not running is skipped. Add your own HUD's hide and show calls in the same way.

#Showroom

The talk screen has a 3D Showroom card when Showroom.Enabled = true and the Config.Prop.Assets resource (fx-phone-assets) is started.

  1. The clerk sets a phone on the counter in the player's current colour. The camera moves in.
  2. The player drags to turn it and uses the wheel to zoom. Left alone for a few seconds it turns slowly by itself.
  3. Tabs: Colour, Case, Accessory, Name (letters on the back). Everything tried on shows on the phone at once. Under the name field, Height and Left / Right move the name on the back, within Config.Accessories.LetterMove (see Cases and accessories).
  4. Parts the player does not own go into the Cart. Pay and wear buys them and puts the look on the player's phone.

Cases, accessories and letters are bought from the official accessory store at the prices in Config.Accessories, paid from the bank: see Cases and accessories. A colour change is bought as this shop's case product, paid as Payment says. If the shop does not sell the colour picked, the cart says so.

Admins (the fxphone.admin ace or a framework admin) also see a Position tab: it moves where each accessory slot sits on the phone, and Save applies the positions for every player.

Option Default What it changes
Showroom.Enabled true The showroom card
Showroom.Offset vector3(0.0, 0.55, 0.32) Where the phone stands, from the clerk: right, forward, up
Showroom.CamDistance 0.42 Camera distance from the phone, in metres
Showroom.OnCounter true The phone stands on the surface under the Offset spot (the counter). Without a surface there, the Offset height is used
Showroom.Lift 0.0 Raises the phone from the counter, in metres
Showroom.Fov 40.0 How wide the lens opens, 12 (close-up) to 58 (far). The wheel zooms from there
Showroom.Light.Enabled true Three studio lights on the phone
Showroom.Light.Intensity 1.0 Light strength. 1.5 brighter, 0.6 softer. By day they run at less than half

#Business (Business)

With Business.Enabled = true the shops are a player business run by one job (Job, default 'phoneshop').

#What changes

  • Sales go to the job's bank account, minus the commission of the employee who served. Without the business, the money simply leaves the economy. A sale with a moved player's welcome gift is booked at the lower price paid (see Welcome gift for moved players).
  • Physical goods have stock. The kinds in Stocked (phone, sim, sim_prepaid by default) are counted per shop. Each starts at StartStock the first time the shop sells it. At 0 the product is out of stock until a manager orders more.
  • Employees can serve at the counter. While an employee is on duty at a shop, a customer's purchase waits for their approval. With nobody on duty, the clerk NPC sells as usual.

#For employees

An employee opens the talk screen at the counter like a customer and gets a Business panel.

  • Clock in / Clock out at that shop. They are clocked out automatically when they walk further than DutyRange metres, leave the job or leave the server.
  • Counter: the waiting customers. Approve (with a discount up to the shop's limit) or Decline. Their sales and commission today.

A waiting customer sees "One moment, my colleague will take care of you." If nobody answers within AnswerSeconds, the clerk NPC sells it (if the customer is still at the counter). A customer who closes the talk screen cancels their request. A shop holds at most 8 waiting requests; beyond that the NPC sells at once.

#For managers

Grade ManagerGrade and up, or the job's boss, also see:

Tab What it does
Stock Orders stock for a product, paid from the job account at Wholesale times the base price, up to MaxStock
Prices Sets the shop's price per product, between PriceRange times the base price. The eye takes a product off sale
Prices > Counter rules Commission for staff (up to Commission.Max) and the most staff may discount (up to MaxDiscount)
Books Account balance, sales in the last 24 hours and 7 days, recent sales and who made them

Prices, stock and rules are per shop.

#What you need

  • A job called Job in your framework, with grades.
  • A bank adapter with job accounts (Config.Bank.Adapter), so sales can be paid in and stock paid for.
  • Something to hire staff and manage the account: fx-companyapp, or your framework's boss menu.

#Options

Option Default What it changes
Business.Enabled true The shops are a business
Business.Job 'phoneshop' The job that runs every shop
Business.ManagerGrade 3 This grade and up manage prices, stock, rules and the books
Business.PriceRange { 0.8, 1.6 } Managers price each product between these factors of its base price
Business.Wholesale 0.55 Stock costs this factor of the base price
Business.Stocked { phone = true, sim = true, sim_prepaid = true } Kinds that are goods on a shelf
Business.StartStock 20 Stock per stocked product the first time a shop sells it
Business.MaxStock 250 Most stock per product
Business.Commission.Default 10 Percent of a sale paid to the employee who served it, until a manager changes it
Business.Commission.Max 30 Highest commission a manager may set
Business.MaxDiscount 20 Highest discount a manager may allow at the counter, percent
Business.DutyRange 35.0 Metres an employee may walk from the shop before they are clocked out
Business.AnswerSeconds 30 How long a customer's request waits for staff before the NPC sells (at least 5)

#Options

Option Default What it changes
Enabled true Switches the shops on. The admin tablet can override it while the server runs
Payment 'both' 'cash', 'bank' or 'both' (cash first, then bank)
Hours 'always' 'always': every shop is open round the clock (its own hours are kept but not used). 'game' / 'real': opening hours follow the game clock or the server's real time
CasesChangeVariation true case products recolour the phone. false: they hand out an item instead (each needs an item field)
Interaction 'auto' 'auto': ox_target when it runs, otherwise a prompt and E. 'prompt': always the prompt
SpawnDistance 60.0 Metres at which the clerk is created
DespawnDistance 80.0 Metres at which the clerk is removed
NpcModels 4 models Clerk models the tablet offers
NpcScenarios stand, phone, clip Clerk idle scenarios, by key and scenario
Talk.CamDistance 1.9 Camera distance from the clerk
Talk.CamMinDistance 0.95 Closest the camera comes when the player stands close
Talk.CamFov 42.0 Camera field of view
Talk.CamMaxFov 68.0 Widest it opens when it moves in
Talk.CamHeight 0.45 Camera height
Talk.CamLookHeight 0.3 Height the camera looks at on the clerk
Talk.CamShift 0.3 Sideways shift so the clerk stands beside the panel
Talk.CamEase 900 Camera move time, ms
Talk.TypeMs 1000 Time a line takes to type out; the clerk's mouth moves as long
Talk.BackgroundBlur true Blurs the background behind the clerk
Talk.Bubble.Enabled true The clerk's line beside their chest. false: at the bottom of the screen
Talk.Bubble.Height 0.28 Metres above the clerk's middle
Talk.Bubble.Side 0.07 How far right of the clerk, as a share of the screen width (negative: left)
Hud.OnOpen, Hud.OnClose wais-hudv6, fx-hud Functions that hide and show your HUD

#Setting it up

  1. Add the phone item, and sim_card if you use SIM cards: Item setup.
  2. Check the shop positions in game. Move them on the admin tablet (Shops, Here), or change Shops before the first start.
  3. For SIM products, switch on Config.Sim.Enabled (SIM cards).
  4. For the showroom, ensure fx-phone-assets in server.cfg. Players who were connected when it was started must reconnect to load its models.
  5. Business: create the phoneshop job, check your bank adapter has job accounts, hire staff. Or set Business.Enabled = false.

#Good to know

  • Business is on by default. If the Business.Job job ('phoneshop') does not exist on your server, the business stays off by itself: the console says so once, the clerks sell, and nothing is stocked, so nothing runs out. Create the job to use the business, or set Business.Enabled = false to silence the warning. A job added later is picked up within a few minutes.
  • No SIM products in the list. Config.Sim.Enabled is false. Prepaid SIMs also need prepaid = true on the shop.
  • No phones or SIM cards for sale. No inventory was detected (Config.Inventory), so items cannot be handed out.
  • The colour cases disappeared. CasesChangeVariation = false and the case products have no item.
  • I changed a shop in config.lua and nothing happened. Shops live in the database after the first start. Use the tablet, or give the entry a new key.
  • The shop is "closed" at the wrong time. With Hours = 'game' the server reads the game time that a time sync resource (such as Renewed-Weathersync) publishes in GlobalState.currentTime. Without one it uses the server's real hour. The blips on every player's map follow the same hour as the server, never the player's own clock.
  • ox_target is running but you want the E prompt. Set Interaction = 'prompt'.
  • Phones charge at the counter. With Config.Battery.ChargeAtShops = true a phone charges while its owner stands near a shop. See Battery and signal.
  • Shop purchases are logged as shop.purchase; business actions as shop.duty, shop.restock and shop.price.