> 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

This is the guide for the cinquina's sims FiveM script. Please read everything before opening a ticket on our Discord Server

## 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
    }
}

```

### lb-phone Modification

Add to the end of the file  `lb-phone/client/custom/functions/functions.lua` these lines of code:

```lua
CreateThread(function ()
    while not SetPhone do
        Wait(500)
    end
    exports("SetPhone", SetPhone)
end)
```

Then go to `lb-phone/client/custom/frameworks/qbox/item.lua` and edit `CanOpenPhone` function to

```lua
function CanOpenPhone()
    local phoneNumber = exports["lb-phone"]:GetEquippedPhoneNumber() 

    if not phoneNumber then
        return false
    end

    return true
end
```

***

## 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.