Narguile/Hookah System and Job - Standalone

tiutoxico_narguile includes portable hookahs and stoves, a shop, gathering, crafting and staff management.

1. Enable OneSync and place the folder in your server resources.
2. Configure locations, inventory and money in the files below.
3. Start chosen dependencies first. For vRP or oxmysql storage, uncomment its library in fxmanifest.lua.
4. Add ensure tiutoxico_narguile to server.cfg.
5. With the intended owner online, run narguile_owner ID in the console, replacing ID with the player server ID. Manage staff at the shop office.

The initial setup uses the resource inventory and stock. Configure money integration to charge purchases and pay staff; purchases are free without it.

Set Config.LocationProfile for your city: custom uses the locations you define; outdoor provides a coordinate-based shop example; portable enables a free portable demonstration with shop and production disabled. The default weed profile uses tiutoxico_weed coordinates; use it when installing at that MLO, or choose another profile and adjust the locations.

Tables, shelves, register, office, storage, clock-in, gathering, supplier and stations are configurable. Check the locations in game after editing. Generated recipes use the kiln and mixing IDs; preserve these when rearranging stations. For an exact workstation position, use pos and search = 0.

Config.Security.allowedBuckets selects the shop dimensions; the default is { 0 }. Portables belong to their placement dimension. Preserve existing point IDs to retain saved state.

Set Config.Inventory.mode to own for the resource inventory, external for framework inventory or free to use without consuming items. Presets: ox_inventory, qb, esx, vrp, qs and core. Map different names in Config.Inventory.items.

Select Config.Money.preset: qb, esx, vrp or ox. Set the account in Config.Money.account. APIs are in editable, server-only bridges/presets.lua; adapt them when your framework version uses different calls.

Config.Stock.mode accepts own or external. The ox_inventory preset uses a dedicated stash with id, label, slots and maxWeight. Transfer products through shop storage to preserve commission authorship.

Set Config.Interaction.mode: auto, marker, ox_target or qb-target. Target APIs are in bridges/target.lua; resource names in Config.Interaction.resources and automatic priority in Config.Interaction.autoOrder.

Config.Inventory.mode = 'external'
Config.Inventory.preset = 'esx'

Config.Money.preset = 'esx'

Config.Inventory.mode = 'external'
Config.Inventory.preset = 'qb'

Config.Money.preset = 'qb'

Config.Inventory.mode = 'external'
Config.Inventory.preset = 'vrp'

Config.Money.preset = 'vrp'

Config.Inventory.items = { hookah_1 = 'city_hookah_green', water = 'hookah_water' }

Buy from shelves when stock is available. The shop works without online employees. Use /narguile for the equipment bag and /bestbuds for the production bag. External mode keeps products in your framework inventory.

For administrator tools, see Opening the Staff panel.

Select equipment, confirm its position and interact to add water, flavor and coal. Other players may use and refill portables; the player who placed them may pack them. Authorized employees manage shop tables.

Employees clock in when required, gather ingredients, craft at stations and deliver to storage. Deliver all sends recipe outputs and commission-eligible items; other ingredients stay in the bag.

Change or disable commands with Config.Obtain.command and Config.Production.command. Set type prices in Config.Shop.prices and item prices in Config.Shop.itemPrices.

Default controls: E to smoke, X to drop and G to take the hose. Set control IDs and labels in Config.Hookah.controls: smoke, drop and takeHose.

Config.Cooperation.seating configures seating. The initial setup recognizes tiutoxico_weed; use enabled = false to disable or resource for another resource exposing SeatState(). For another API, provide state returning {seated, busy, controls, transitionUntil, interacting}.

Pose changes interrupt the puff and keep the hose in hand. Release the smoking key before the next puff. Set the seated animation in Config.Hookah.seatedAnimation. Client exports HookahHoseInHand(), HookahInteractionState() and HookahSuspendSmoking(ms) support other interactions.

Use the office to hire staff, assign roles and edit names. An empty name restores automatic naming; Config.Identity.name can retrieve character names from your framework.

In the Roles tab, click a role header to expand or collapse its permissions; scroll inside the panel to reach the other roles.

Config.Permissions.roles defines initial owner, manager and employee roles. Use nameKey for translated names or name for a custom name. Existing roles retain their settings. Use Config.Permissions.roleOverrides to change existing role permissions: true grants and false revokes.

In the panel, the Owner orders permissions from highest to lowest by dragging or using move-up/down controls. Set the initial order in Config.Permissions.permissionOrder. Only the Owner can grant any permission. Others grant only permissions they hold that rank below their own highest permission; higher roles are protected. Only an Owner can promote someone to Owner.

roles permits creating, renaming and removing roles. Editing permissions also requires assignPermissions. Assigning staff roles requires staff and assignPermissions. Without assignPermissions, hiring uses employee within the hierarchy limits.

reviewPayments and reviewWithdrawals delegate payment and withdrawal reviews. manageOwners permits management of owner records within the promotion rule. ownerAllPermissions controls full Owner access; protectLastOwner preserves the last owner; allowSelfManagement allows editing your own staff record.

For framework roles, configure role and isOwner; nil/false deny corresponding access. When using Config.Identity.resolve for character IDs, migrate existing records before changing the identity format.

Opening the Staff panel

Open /narguile or /bestbuds and click Staff. The button also appears in storage for authorized administrators who have access to it. There is no separate command for this panel; the commands above are defaults and can be changed in the configuration.

Use this panel’s NUI tab to customize the shop appearance; see Names, branding and appearance.

If the button is missing, configure authorization in config_server.lua: use Config.Permissions.isStaff, the Config.Permissions.staff list or Config.Permissions.ace.staff, which defaults to hookah.staff. Being the shop Owner does not automatically grant this access; the staff role permission allows hiring and firing shop employees.

ACE: in server.cfg, authorize the administrator group used by your server. The example below uses group.admin; the player must already belong to this group.

add_ace group.admin hookah.staff allow

Classic vRP: uncomment @vrp/lib/utils.lua in the server_scripts section of fxmanifest.lua and place the callback below at the end of config_server.lua. Replace admin.permissao with your framework administrator permission. This example uses Proxy with table arguments; adapt the calls if your framework uses a different API.

local Proxy = module('vrp', 'lib/Proxy')
local vRP = Proxy.getInterface('vRP')

Config.Permissions.isStaff = function(src)
    local userId = vRP.getUserId({ src })
    return userId ~= nil
        and vRP.hasPermission({ userId, 'admin.permissao' }) == true
end

Choose the method that suits your framework. When Config.Permissions.isStaff is defined, its true or false return value decides Staff panel access.

The Config.Permissions.bootstrapAce ACE authorizes the owner registration command in game.

Config.Permissions.roleOverrides = {
    manager = { permissions = { withdraw = true, reviewPayments = true } },
}
-- server.cfg
add_ace group.admin hookah.bootstrap allow

Set the per-unit commission in Config.Business.production.rates. Delivering crafted products creates the credit once; withdrawing and returning the same product does not create another commission. staffOnly limits eligibility to staff.

Optional sales participation is in Config.Business.salesShare. Use revenue (revenue) or profit (profit); profit requires costs in unitCosts or defaultUnitCost. Percentages range from 0 to 100. Exact item rules override families such as coal.

Sales rotate between authors with available units of each product. Unattributed stock and infinite-stock products do not generate participation. View and pay credits in Metrics.

-- config_server.lua
Config.Business.production.rates = { coal = 6, flavor = 10, water = 1 }
Config.Business.production.staffOnly = true
Config.Business.salesShare.enabled = true
Config.Business.salesShare.percent = 10
Config.Business.salesShare.itemPercent = { water = 5, flavor = 15 }
Config.Business.salesShare.basis = 'profit' -- or 'revenue'
Config.Business.salesShare.unitCosts = { water = 2, coal = 8, flavor = 12 }
Config.Business.decimals = 2 -- 0 for integer-only money APIs

Open Metrics at the shop office with the metrics permission. Select period, employee and line, bar or table view to inspect production, sales, assemblies and payments. Pending balance is the current amount owed, regardless of the period. Resetting charts preserves payable amounts.

payroll allows credit payments; reviewPayments allows pending-payment review. Select an employee and amount within their available balance. payer = "register" uses shop funds; external uses your integration. Standard payouts require the employee online. Configure payStaff for offline payouts or another currency.

Choose manual or automatic in Config.Business.payouts.mode. Unconfirmed payments remain reserved for review. Check the money system before marking paid or unpaid.

Config.Business.payouts.mode = 'manual'
Config.Business.payouts.payer = 'register'
Config.Business.metrics.defaultDays = 30
Config.Business.metrics.periodOptions = { 7, 14, 30, 60, 90 }
Config.Business.metrics.dayOffsetHours = -3
Config.Business.decimals = 2

The default Config.Storage.mode = "json" saves to dados/narguile.json. For database storage, choose oxmysql, configure the connection and enable its manifest library. Use custom for another backend.

Before updating, stop the resource and back up data and configuration. Install new files and reapply settings while preserving location IDs. Keep the existing JSON or database; the empty package file is for first installation.

If STORAGE BLOCKED appears, check file access or database connection and restart after fixing the cause. Preserve data and backups. Check pending financial operations externally before reconciliation.

Select Config.Locale: pt-br, en or es. Text lives in locales/*.lua. Use Config.TextOverrides to replace selected text.

1. Copy locales/template.lua, for example to locales/de.lua.
2. Change Locales["my-lang"] to Locales["de"] and translate the values.
3. Set Config.Locale = "de".
4. Set ui.formatLocale = "de-DE" in the language file for numbers and dates.

Preserve keys and placeholders such as %s, %d and {amount}. Missing text falls back to Portuguese.

ui.shopName defines the translated default shop name; a custom name saved in the NUI tab takes priority.

-- config.lua: override selected labels without editing the language file
Config.TextOverrides = {
    ui = {
        metrics_title = 'Business dashboard',
        metrics_units = 'Units',
        formatLocale = 'en-US',
        durationSeconds = '{seconds} s',
        durationHoursMinutes = '{hours} h {minutes} min',
        permPayroll = 'Pay employee credits',
    },
    messages = { business_paid = 'Payment completed.' },
}

In the Staff panel, open the NUI tab, enter a Shop name (up to 64 characters) and click Apply. The name is saved for all players. Default restores Config.UI.shopName or, when it is nil, the selected locale’s ui.shopName text.

Set the default image in Config.UI.logo and adjust scale and color in Config.UI. The log name is in Config.Logs.name.

Products, models, stations, recipes and gathering points use nameKey for translation. A literal name takes priority. Categories use labelKey/label; steps use textKey, hintKey and errorHintKey. Preserve nameArgs arguments where present.

Config.Obtain.hookah and Config.Obtain.stove accept bag to take from inventory, free to place without an item or item for a framework-registered item.

In item mode, the usable-item callback calls HookahPlace. Configure Config.Hooks.onPlace to consume after position confirmation and Config.Hooks.onPack to return on packing. Confirm completion with true. Opening or cancelling the preview should not consume the item.

Register external items: hookah_1 through hookah_8, stove, hose, water, flavor_<key>, coal_<key>, coconut, tobacco, molasses, fruit_<key> and configured extras. Mutation exports are server-side and should be called by authorized resources.

-- config_server.lua, external inventory example (script item names must be mapped)
Config.Hooks.onPlace = function(src, kind, model)
    local item = kind == 'hookah' and ('hookah_' .. model) or 'stove'
    item = Config.Inventory.items[item] or item
    return exports.ox_inventory:RemoveItem(src, item, 1)
end
Config.Hooks.onPack = function(src, kind, model)
    local item = kind == 'hookah' and ('hookah_' .. model) or 'stove'
    item = Config.Inventory.items[item] or item
    return exports.ox_inventory:AddItem(src, item, 1)
end
-- In your framework's usable-item callback: only authorize/open the preview.
-- exports.tiutoxico_narguile:HookahPlace(src, 'hookah', 1)
-- ox_inventory server.export receives (event,item,inventory,slot,data), not src/kind/model.
-- Write a wrapper using inventory.id and the intended kind/model; do not point it directly to HookahPlace.

Configure ingredients, recipes, duration, quantity, steps and stations in Config.Production. Recipes define inputs and outputs; steps accept hold, taps, stop, keep or wait.

Config.Production.protection defines blocked controls and cancellation during work. Animation menus, character changes and healing should check IsNarguileBusy before interrupting the activity. Call without arguments on the client and pass the affected player on the server.

-- Integration with other resources:
-- CLIENT
if GetResourceState('tiutoxico_narguile') == 'started'
    and exports.tiutoxico_narguile:IsNarguileBusy() then
    return
end
-- SERVER (source is the player affected by the command)
if GetResourceState('tiutoxico_narguile') == 'started'
    and exports.tiutoxico_narguile:IsNarguileBusy(source) then
    return
end
-- State: Player(source).state.narguileBusy; client extra: narguileClientBusy
-- config.lua
Config.Production.protection.enabled = true
Config.Production.protection.blockControls = { 73, 167, 45, 24, 25, 37 }
Config.Production.protection.abortOnPedChange = true
Config.Production.protection.abortOnDeath = true
Config.Production.protection.cancelKey = 177 -- BACKSPACE; false disables intentional cancellation
Config.Production.protection.animationRestoreAttempts = 2
Config.Production.protection.animationRestoreGraceMs = 1800

Use callbacks to connect APIs that differ from the presets. Keep money, permissions, webhooks and credentials in config_server.lua, which loads only on the server.

An external operation returns true after completion, false when nothing changed or nil/an exception when the result is unknown. Uncertain operations await review. Check the inventory or money system before reconciliation.

Review withdrawals in Register with reviewWithdrawals and staff payments in Metrics with reviewPayments. Marking paid or unpaid adjusts record and reservation; it does not issue another payment. Restart this resource after restarting ox_inventory.

Custom inventory uses count/remove/add; list/canAdd are optional. Without list, catalog items are queried individually. External stock uses count/add/remove.

Config.Money.charge/pay/refund(src, amount, reason, transactionId, identity, session) receives the original identity. For staff payments, use payStaff(identity, onlineSourceOrNil, amount, reason, transactionId, sessionOrNil). Store transactionId externally when available to prevent duplicate payments.

Async callbacks must keep the player bound to the original identity and validate HookahSessionValid(session) immediately before changing data after a wait. HookahSessionCapture(src) obtains the token. External inventory, stock and protected hooks receive session last.

HookahOperationReviews(identityOrNil) lists pending operations. After checking and reconciling external effects, call HookahResolveOperation(transactionId, {verified=true, reference="receipt"}). The reference must contain 1 to 160 characters. This export records reconciliation; deliveries, returns and financial corrections must be complete before calling it.

Custom storage: load(callback) calls callback(data, nil) or callback(nil, error); save(data) returns true after writing.

Use this reference to locate the main configuration blocks.