> For the complete documentation index, see [llms.txt](https://docs.cinquina.lol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cinquina.lol/cinquinas-sims.md).

# cinquinas-sims

## Installation

Installation is easy and basically drag-n-drop. 

1. Drag `cinquinas-sims` and `cinquinas-sims-app` <sup>(if you need lb-phone's eSIMs app)</sup> into your server files. Just make sure that it is started after **ox\_lib**, **ox\_inventory**, **oxmysql** and **lb-phone**.
2. Import `cinquinas-sims/IMPORTME.SQL` into your server's database. If you are using [HeidiSQL](https://www.heidisql.com/), you can refer to [this guide](https://help.vibegames.com/en/article/how-to-import-an-sql-file-via-heidisql-pedsp2).
3. Append the items `cinquinas-sims/setup/items.lua` to your `ox_inventory/data/items.lua` \
   ⚠ Make sure to replace the `phone` item with the one indicated in `cinquinas-sims/setup/items.lua`&#x20;

```lua
-- your other items ..
["simcard"] = {
    label = "SIM Card",
    weight = 50,
    stack = false
},

["phone"] = {
    label = "Phone",
    weight = 190,
    stack = false,
    consume = 0,
    buttons = {
        {
            label = 'SIM Stash',
            action = function(slot)
                TriggerServerEvent("cinquinas-sims:lib:openSimStash", slot)
            end
        },
    }
},
```

4. **THIS IS NOT MANDATORY** but you can add our Digital Den preset from `cinquinas-sims/setup/shop.lua` to `ox_inventory/data/shop.lua`

```lua
-- your other shops..
DigitalDen = {
    name = 'Digital Den',
    inventory = {
        { name = 'simcard', price = 500 },
        { name = 'phone',   price = 1000 },
    },
    locations = {
        vec3(1138.1888, -470.7543, 66.6694)
    },
    blip = {
        id = 772, colour = 27, scale = 1.0
    }
}

```

***

## Configuration

### cinquinas-sims

```lua
Config = {}

-- Developer mode, set to true to enable debug prints
Config.Debug = false

Config.Framework = "qbx" -- qbx, qbcore, esx

-- Do not change this unless you've changed your phone item name on lb-phone
Config.PhoneItemName = "phone"
Config.SIMItemName = "simcard"
```

This is our config, please do not change anything but the `Config.Framework` value, according to the framework you are currently using on your server.

### cinquinas-sims-app

```lua
Config = {}

Config.Debug = false
Config.Framework = "qbx" -- qbx, qbcore, esx

Config.App = {
    Default = true, -- should the app be installed by default? this also means that you can't uninstall it
    Price = 0, -- OPTIONAL: require players to pay for the app with in-game money to download it
    Description = "App to manage and buy your eSIMs", -- The description that will appear on the app store
}

Config.ESims = {
    Price = 120, -- Price for a new eSIM
    Maximum = 0, -- Maximum amount of eSIMs a player can buy, put 0 for infinite
    Plan = {
        name = "eSIM",
        subtitle = "Navigate everywhere in the United States"
    }
}

Config.Translations = {
    ["phone_not_found"] = "Phone has not been found",
    ["no_esims"] = "You've no eSIMs.",
    ["esim_not_found"] = "This eSIM does not exists",
    ["failed_to_clear_esim"] = "eSIM could not be cleared.",
    ["failed_to_set_esim"] = "eSIM could not be activated",
    ["esim_successfully_set"] = "eSIM has been successfully activated",
    ["no_money"] = "You've no money!",
    ["invalid_owner_number"] = "Cannot get phone owner",
    ["max_esims_reached"] = "You cannot buy no more eSIMs",
    ["db_error"] = "Please contact your server administrator."
}
```

This configuration file is also pretty self-explanatory, just make sure to change always your `Config.Framework` to your current server's framework.

## Customization

### Notifications

To use your personal notification system, you can change the exports from `cinquinas-sims-app/client/editable.lua`

```lua
-- cinquinas-sims-app/client/editable.lua
function ShowNotification(text, type)
    exports.qbx_core:Notify(text, type or "info")
end
```

## F.A.Q.

### Should I reset my phone database in order to use this script?

No, the script will automatically fetch the old number and put it as a physical SIM that players can remove and reuse.

### Can I adapt this script for my custom framework?

Yes, you can, by editing all the unescrowed lua files.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.cinquina.lol/cinquinas-sims.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.