# Server *** ### getPlayerData Loads the full hotdog-cart player row from the database. Creates a default row if none exists yet. ```lua exports['axiam_hotdogcart']:getPlayerData(citizenid) ``` * **citizenid:** `string` - Framework character id (e.g. QBCore `citizenid`). **Return:** * `table` - Player row, or `nil` if `citizenid` is invalid. | Field | Type | Description | | -------------------- | -------- | ------------------------------ | | `citizenid` | `string` | Character id. | | `level` | `number` | Hotdog cart level. | | `xp` | `number` | Current XP. | | `total_served` | `number` | Lifetime customers served. | | `total_lost` | `number` | Lifetime customers lost. | | `total_earnings` | `number` | Lifetime sales earnings. | | `avg_rating` | `number` | Lifetime average star rating. | | `total_reviews` | `number` | Lifetime review count. | | `tutorial_completed` | `number` | `0` or `1`. | | `inventory` | `string` | Pantry stock as JSON. | | `created_at` | `string` | Row created timestamp (MySQL). | | `updated_at` | `string` | Row updated timestamp (MySQL). | *** ### getPlayerValue Reads a single column from the player row. ```lua exports['axiam_hotdogcart']:getPlayerValue(citizenid, key) ``` * **citizenid:** `string` * **key:** `string` - Column name (see writable fields below). **Return:** * `any` - Field value, or `nil` if `citizenid` / `key` is invalid or the row is missing. *** ### setPlayerValue Writes a single allowed column on the player row. ```lua exports['axiam_hotdogcart']:setPlayerValue(citizenid, key, value) ``` * **citizenid:** `string` * **key:** `string` - Must be an allowed column (see below). * **value:** `any` - For `inventory`, you may pass a `table` (encoded to JSON automatically). **Return:** * `boolean` - `true` if the field was accepted and queued for update; `false` if validation failed. The MySQL update runs asynchronously after `true` is returned. *** ### setPlayerData Writes multiple allowed columns in one update. ```lua exports['axiam_hotdogcart']:setPlayerData(citizenid, fields) ``` * **citizenid:** `string` * **fields:** `table` - Keys are column names; unknown keys are ignored. **Return:** * `boolean` - `true` if at least one allowed field was written; `false` otherwise. *** ### getPlayerValueBySource Same as `getPlayerValue`, resolving `citizenid` from a server id. ```lua exports['axiam_hotdogcart']:getPlayerValueBySource(source, key) ``` * **source:** `number` - Player server id. * **key:** `string` **Return:** * `any` - Same as `getPlayerValue`, or `nil` if the player cannot be resolved. *** ### setPlayerValueBySource Same as `setPlayerValue`. ```lua exports['axiam_hotdogcart']:setPlayerValueBySource(source, key, value) ``` * **source:** `number` * **key:** `string` * **value:** `any` **Return:** * `boolean` *** ### setPlayerDataBySource Same as `setPlayerData`. ```lua exports['axiam_hotdogcart']:setPlayerDataBySource(source, fields) ``` * **source:** `number` * **fields:** `table` **Return:** * `boolean` *** #### Writable player fields Only these keys are accepted by `setPlayerValue` and `setPlayerData`: | Key | Type | Notes | | -------------------- | ------------------- | ----------------------------------------------------------------- | | `level` | `number` | | | `xp` | `number` | | | `total_served` | `number` | | | `total_lost` | `number` | | | `total_earnings` | `number` | | | `avg_rating` | `number` | | | `total_reviews` | `number` | | | `tutorial_completed` | `number` | `0` or `1` | | `inventory` | `string` or `table` | Pass a table when setting; `getPlayerValue` returns a JSON string | *** ### getPlayerProgression Alias for `getPlayerData`. ```lua exports['axiam_hotdogcart']:getPlayerProgression(citizenid) ``` * **citizenid:** `string` **Return:** * `table` or `nil` *** ### addXP Adds XP for a character. Amount is floored, capped by `Progression.maxXpPerEvent` in config, and ignored if `amount <= 0`. If that player is online and owns an active cart, the client receives `hotdogcart:xpAwarded` and optionally `hotdogcart:levelUp`. ```lua exports['axiam_hotdogcart']:addXP(citizenid, amount) ``` * **citizenid:** `string` * **amount:** `number` - Positive XP to add. *** ### getPlayerEarnings Returns lifetime `total_earnings` for a character. ```lua exports['axiam_hotdogcart']:getPlayerEarnings(citizenid) ``` * **citizenid:** `string` **Return:** * `number` - `0` if the player row is missing or `citizenid` is invalid. *** ### getActiveCartCount Returns how many hotdog carts are currently registered on the server. ```lua exports['axiam_hotdogcart']:getActiveCartCount() ``` **Return:** * `number` *** ### startHotdog Tells a client to start a shift (same as using the shift item). ```lua exports['axiam_hotdogcart']:startHotdog(source) ``` * **source:** `number` - Target player server id. **Return:** * `boolean` - `true` if the client event was sent; `false` if `source` is invalid. *** ### endHotdog Tells a client to cancel or end their shift. ```lua exports['axiam_hotdogcart']:endHotdog(source) ``` * **source:** `number` **Return:** * `boolean` - `true` if the client event was sent; `false` if `source` is invalid. *** ### isPlayerWorking Checks whether a player currently **owns a registered cart** on the server. ```lua exports['axiam_hotdogcart']:isPlayerWorking(source) ``` * **source:** `number` **Return:** * `boolean` - `true` if that player is the owner of an entry in the cart registry. This is not the same as the client `isWorking` export, which follows the local flow state machine (`tutorial` / `active` / `closing`). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.axiam.shop/axiam_hotdogcart/exports/server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.