> For the complete documentation index, see [llms.txt](https://uniqers-scripts-docs.gitbook.io/uniqers-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uniqers-scripts-docs.gitbook.io/uniqers-scripts-docs/uniqers-marriage.md).
# uniqers-marriage
How to install and all exports infos.
## 💍 Uniqers Marriage Script - Official Documentation
Welcome to the official documentation for the Uniqers Marriage Script. This is not just a simple marriage script; it is a complete roleplay system for couples on your FiveM server. It includes ring proposals, a grand wedding ceremony at venues you build in game, a fully functional Priest job, dynamic surname changes, divorce petitions, a couple's Loyalty (mission) system, weekly leaderboards with automated rewards, a seasonal Valentine's Day event and much more, all in one resource.
* 🛒 **Store:**
* 💬 **Support (Discord):**
***
### 🌟 1. Key Features
**Marriage Hub**
* One screen that brings every marriage page together: your marriage, the married list and rewards, the ceremony, the wedding album, loyalty, the Valentine's event, love messages, the ring shop, the church, invitations, the priest panel and the staff pages.
* Opens with `/marriagehub` or a hotkey. Players only see the cards they can use.
**Rings & Proposal**
* **Ring Shop (`/buyring`):** ring sets (Classic Band, King & Princess, Skull & Solitaire), each with metal colours and a glow version.
* **Two ring modes:** one set for the couple, or a separate ring for each spouse (see `NeedTwoRing`).
* **Ring Delivery:** the ring is brought by a courier van or by a drone that lowers the box on a rope.
* **Custom streamed rings, ring boxes and a custom proposal animation.**
* **Proposal Message & Timer:** the proposer writes a personal message. The other player has 25 seconds to answer, otherwise the proposal is declined automatically. Both players see a countdown HUD.
* **Ring Guard:** exports for clothing scripts, so players can't save a wedding ring that isn't theirs from their clothing menu.
**Priest Job & Marriage**
* **Priest Job System:** a complete progression system for priests with XP, levels and payouts. Priests manage marriage applications, spawn church vehicles and perform weddings. It can also run 100% with NPC priests.
* **Dynamic Surname & Metadata Updates:** couples can keep their names, take their spouse's surname or create a custom one. The script updates the database and the character, and re-issues identity items (ID Card, Driver's License...) with the new name.
**Grand Ceremony & Venues**
* **Venue Editor (`/ceremonyadmin`):** staff build ceremony venues in game with a raycast editor: the priest's route, the couple's start and stand points, effect points, fireworks, the aisle, speakers, the venue area and a party area.
* **Booking:** couples pick a venue on an interactive map, compare venues side by side and book a date and time on a calendar.
* **Cinematic Ceremony:** the couple walks down the aisle, the priest's speech with subtitles, the vows and signing the marriage certificate, then fireworks, confetti, flames, champagne or money rain.
* **Music & Party:** live music from the venue speakers (xsound, YouTube links) and colourful moving party lights.
* **Invitations:** an invitation designer with templates, a guest list and a wedding invitation item.
* **Wedding Album:** photos and selfies taken during the celebration, kept in a book you can leaf through from the hub.
* **Wedding Car Rental:** rent a wedding car with a refundable deposit.
* City-wide announcement before the ceremony, refunds on cancel, no-show and reconnect handling.
**Couple Life**
* **Married List (`/marriedpanel`):** every married couple of the city, with anniversary badge rewards (1, 3, 6 months and 1 year).
* **Spouse Tracking:** use the wedding ring to mark your spouse on the map, a live GPS blip and a floating 3D heart emoji above your spouse's head when close.
* **Mini HUD:** a movable marriage HUD.
* **Love Scenes (`/lovemessage`):** send your spouse a love kiss, a secret letter, a teddy bear surprise, a rose garden, a heartbeat or fireworks with your own message.
**Loyalty System & Weekly Leaderboard**
* **Missions:** couples earn points by completing Legal (buying gifts, flowers, romantic moments) and Illegal (co-op store robberies, luxury car thefts with a hacking mini game) missions together.
* **Weekly Leaderboards & Rewards:** automated weekly resets. The top couples automatically receive configurable rewards (cash, items, vehicles with unique plates and loyalty cards).
**Valentine's Day Event**
* A time-limited UI where couples complete tasks together (taking a photo, sending a gift, drinking wine, showing their love, sleeping together) to earn rewards. It opens by itself every year between the dates you set.
**Divorce**
* **Divorce Petition:** a petition with a reason and a signature, filed at the priest. One-sided or two-sided divorce (see `ConsensualDivorce`).
* **Name change** after a divorce.
**Staff Tools**
* Marriage admin panel (`/marriedadmin`), multiple marriage panel, `/givering`, the venue manager, a staff permission check and Discord logs.
**Integrations**
* **uniqers-smartring:** the wedding ring can be bought as a smart ring (spouse status, distance, heart rate, GPS and a private radio channel).
* **uniqers-coupleanims:** couple animations open right from the Marriage Hub.
**Compatibility**
* **Frameworks:** QBCore, Qbox, ESX (Legacy and old) and Qbus, detected automatically.
* **Inventories:** ox\_inventory, qb-inventory, ps-inventory, qs-inventory and others.
* **Interaction:** ox\_target, qb-target or DrawText 3D.
* **Clothing:** qb-clothing, esx\_skin / skinchanger, fivem-appearance, illenium-appearance, rcore\_clothing, tgiann-clothing or your own script.
* **Database:** oxmysql, mysql-async or ghmattimysql.
* **Languages:** English, Turkish, German, French, Spanish, Portuguese and Russian. You can add your own.
***
### 🛠️ 2. Installation Guide
#### 2.1. Dependencies
| Resource | Required | Used for |
| ---------------------- | ---------- | ----------------------------------------------------------------------- |
| oxmysql | **Yes** | Database. The resource loads it even if you choose another SQL wrapper. |
| PolyZone | **Yes** | Interaction zones. |
| screenshot-basic | For photos | Wedding album, the Valentine's photo task and venue photos. |
| xsound | Optional | Ceremony music. |
| ox\_target / qb-target | Optional | Target interaction. Without it, DrawText is used. |
| uniqers-smartring | Optional | Smart wedding ring. |
| uniqers-coupleanims | Optional | Couple animations card in the Marriage Hub. |
#### 2.2. Database Setup
1. Import `databases/uniqers-marriage.sql` into your database. Every table uses `CREATE TABLE IF NOT EXISTS`, so importing it again never deletes data.
2. **ESX only (optional):** to show Discord or Steam avatars on the marriage panel, run the lines in section 2 of the SQL file (*ESX AVATAR COLUMNS*).
3. **Updating from an older version:** missing columns are added automatically when the resource starts, and ring ids from older versions are converted automatically. Section 3 of the SQL file lists the columns for reference.
> ⚠️ **CRITICAL COLLATION CHECK:** The tables are created as `utf8mb4_general_ci`. The `owner` and `married` columns of the `uniqers_marriage` tables must use the same collation as your framework's identifier column (`citizenid` in the `players` table on QBCore / Qbox, `identifier` in the `users` table on ESX). Example: if your players table uses `utf8mb4_unicode_ci`, set the marriage columns to `utf8mb4_unicode_ci` as well, otherwise you get SQL errors ("Illegal mix of collations").
#### 2.3. Adding Items
Copy the item images from the script's `itemimg` folder (`weddingring.png`, `weddingcertificate.png`, `loyaltycard.png`, `weddinginvitation.png`) to your inventory's image folder, then add the item codes. These items carry metadata (ring set, names, dates, invitation details), so keep them unique / not stackable.
| Item | What it does |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `weddingring` | An unused ring starts the proposal. After the wedding, using it marks your spouse on the map (or opens the smart ring). |
| `weddingcertificate` | Shows your marriage certificate. |
| `loyaltycard` | Given to the weekly top couples of the loyalty leaderboard. |
| `weddinginvitation` | Opens the wedding invitation a couple sent you. |
**For QBCore - `qb-core/shared/items.lua`:**
```lua
weddingring = { name = 'weddingring', label = 'Wedding Ring', weight = 0, type = 'item', image = 'weddingring.png', unique = true, useable = true, shouldClose = false, description = 'Wedding Ring :)' },
weddingcertificate = { name = 'weddingcertificate', label = 'Wedding Certificate', weight = 0, type = 'item', image = 'weddingcertificate.png', unique = true, useable = true, shouldClose = false, description = 'Wedding Certificate :)' },
loyaltycard = { name = 'loyaltycard', label = 'Loyalty Card', weight = 0, type = 'item', image = 'loyaltycard.png', unique = true, useable = true, shouldClose = false, description = 'Loyalty Card :)' },
weddinginvitation = { name = 'weddinginvitation', label = 'Wedding Invitation', weight = 0, type = 'item', image = 'weddinginvitation.png', unique = true, useable = true, shouldClose = true, description = 'Wedding Invitation :)' },
```
**For ox\_inventory (Qbox, or QBCore / ESX servers using ox\_inventory) - `ox_inventory/data/items.lua`:**
```lua
["weddingring"] = { label = "Wedding Ring", weight = 10, stack = false, close = true },
["weddingcertificate"] = { label = "Wedding Certificate", weight = 10, stack = false, close = true },
["loyaltycard"] = { label = "Loyalty Card", weight = 10, stack = false, close = true },
["weddinginvitation"] = { label = "Wedding Invitation", weight = 10, stack = false, close = true },
```
**For ESX (SQL Insert):**
```sql
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
('loyaltycard', 'Loyalty Card', 1, 0, 1),
('weddingcertificate', 'Wedding Certificate', 1, 0, 1),
('weddingring', 'Wedding Ring', 10, 0, 1),
('weddinginvitation', 'Wedding Invitation', 1, 0, 1);
```
#### 2.4. Core Modification (QBCore / Qbox ONLY)
To update a player's name instantly after a marriage or a divorce, the script uses the helper functions below. They must be added to your core, otherwise the surname change fails with `attempt to call a nil value (field 'SetNameLast')`.
* **QBCore:** open `qb-core/server/player.lua`, locate the `self.Functions.SetPlayerData` function and paste the code directly above it.
* **Qbox:** open `qbx_core/server/player.lua`, locate `self.Functions.SetPlayerData` inside the `CreatePlayer` function and paste the same code directly above it. The qb-core bridge of qbx\_core must be enabled.
```lua
function self.Functions.SetNameFull(firstname, lastname)
self.PlayerData.charinfo.firstname = firstname
self.PlayerData.charinfo.lastname = lastname
self.Functions.UpdatePlayerData()
end
function self.Functions.SetNameFirst(firstname)
self.PlayerData.charinfo.firstname = firstname
self.Functions.UpdatePlayerData()
end
function self.Functions.SetNameLast(lastname)
self.PlayerData.charinfo.lastname = lastname
self.Functions.UpdatePlayerData()
end
```
> **Custom / refactored `player.lua`:** If your `player.lua` has no `self.Functions.SetPlayerData` line and instead uses `function Player:SetPlayerData(...)` with a `varargMethods` list, do NOT paste the code above. Instead:
>
> 1. Add `'SetNameFull', 'SetNameFirst', 'SetNameLast'` to the `varargMethods` list.
> 2. Paste this directly above `function Player:SetPlayerData(key, val)`:
```lua
function Player:SetNameFull(firstname, lastname)
self.PlayerData.charinfo.firstname = firstname
self.PlayerData.charinfo.lastname = lastname
self:UpdateClient()
end
function Player:SetNameFirst(firstname)
self.PlayerData.charinfo.firstname = firstname
self:UpdateClient()
end
function Player:SetNameLast(lastname)
self.PlayerData.charinfo.lastname = lastname
self:UpdateClient()
end
```
#### ,2.5. Server.cfg Start Order
Start the script after your database, framework, target and dependency resources:
```
# QBCore
ensure oxmysql
ensure qb-core
ensure qb-target
ensure PolyZone
ensure screenshot-basic
ensure xsound # optional: ceremony music
ensure uniqers-marriage
# Qbox
ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_target
ensure PolyZone
ensure screenshot-basic
ensure xsound # optional: ceremony music
ensure uniqers-marriage
# ESX
ensure oxmysql
ensure ox_lib
ensure es_extended
ensure ox_target
ensure PolyZone
ensure screenshot-basic
ensure xsound # optional: ceremony music
ensure uniqers-marriage
```
#### 2.6. Clothing Scripts & Wedding Rings
* The wedding rings and ring boxes are streamed by the script itself; no extra resource is needed.
* All ring settings (sets, metals, prices, clothing slot) are in `shared/outfits.lua`. The full ring guide is in **RING\_SETS.md**, included with the script.
* If the rings show up as a different clothing item because your server has other addon clothing packs, set `DrawableBase` in `shared/outfits.lua` (see RING\_SETS.md > Common problems).
* **Ring Guard:** add one line to your clothing script's save event so players can't save a ring they don't own (see 6.3).
***
### ⚙️ 3. Configuration
Every setting has a comment next to it in the files. Below is an overview of the important ones.
| File | What's inside |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `shared/config.lua` | Framework, economy, marriage & divorce rules, rings, blips, staff, ring delivery, logs, church locations, rewards |
| `shared/commands.lua` | Command names |
| `shared/hub.lua` | Marriage Hub: command, hotkey, card pictures, cards on/off |
| `shared/venues.lua` | Grand ceremony, venues, booking, music, invitations, album, divorce petition, proposal message and timer |
| `shared/outfits.lua` | Wedding outfits, ring sets, metals, ring prices, Ring Guard |
| `shared/loyalty.lua` | Loyalty missions and weekly leaderboard rewards |
| `shared/valentines.lua` | Love scenes and the Valentine's event |
| `shared/priestjob.lua` | Priest levels, priest job names, priest vehicles |
| `shared/interaction.lua` | DrawText / target settings and icons |
| `shared/functions.lua` | Notification and database bridge functions (custom notify goes here) |
| `shared/locales/*.lua` | Languages |
#### 3.1. Framework & Core Settings (`shared/config.lua`)
* **`Locale`**: server language: `"en"`, `"tr"`, `"de"`, `"fr"`, `"es"`, `"pt"` or `"ru"`.
* **`DatabaseSelect`**: your SQL wrapper: `"oxmysql"`, `"mysql-async"` or `"ghmattimysql"`.
* **`Framework`**: `"auto"` (recommended), `"qbcore"`, `"esx"`, `"qbus"` or `"oldesx"`. Qbox is detected automatically and runs as `"qbcore"`.
* **`Notify`**: `"uniqers-notify"` (the script's own notifications, no extra resource needed), `"qbcore"`, `"esx"`, `"standalone"` (chat) or `"custom"` (add your trigger in `shared/functions.lua`).
* **`Inventory`**: `"auto"` detects ox\_inventory, qb/ps-inventory and qs-inventory. Manual values: `"qbcore"`, `"otherqb"`, `"esx"`, `"otheresx"`.
* **`Clothes`**: your clothing script, used to change couples into wedding attire: `"auto"`, `"qb-clothing"`, `"esx-skinchanger"`, `"fivem-apperance"`, `"illenum-apperance"`, `"rcore-clothing"`, `"tgiann-clothing"` or `"custom"`. Write the values exactly as shown here.
* **`InteractionMethod`** (`shared/interaction.lua`): `"auto"`, `"DrawText"` or `"Target"`. **`targetSystem`**: `"auto"`, `"ox_target"` or `"qb-target"`.
* **`ForEsxAvatar`** (ESX): avatar source on the marriage panel: `"steam"`, `"discord"` or `""`. `DiscordBotToken` is needed for Discord avatars.
* **`Locations`**: the churches: NPC priest position and model, blip, priest garage and the wedding car spawn point. You can add as many as you like.
#### 3.2. Marriage & Divorce
* **`NPCFunction`**: `"yes"` = NPC priests handle marriages and divorces (players with the priest job can still use the commands). `"no"` = everything is done by players with the priest job.
* **`JobsRequest`** (`shared/priestjob.lua`): `"yes"` = marriage requests are accepted by a player priest. `"no"` = the NPC does everything.
* **`CommandsJobs`** (`shared/priestjob.lua`): `"yes"` = players with the priest job can use `/marriage` and `/divorce`.
* **`EnableDivorce`**: `false` = nobody can divorce (staff can still remove a marriage in `/marriedadmin`).
* **`ConsensualDivorce`**:
* `"yes"`: one spouse is enough. The marriage ends as soon as one spouse signs the divorce petition at the priest.
* `"no"`: both spouses are needed. One spouse files the petition, the other reads and signs it at the priest.
* **`DivorcePetition`** (`shared/venues.lua`): the petition paper, the priest distance and the divorce reasons.
* **`MultiMarriage`**: `true` = players can marry more than one person.
* **`PreparationTime`**: wait time (in minutes) for the marriage documents to be prepared.
* **`WeddingPay`**: fee to apply for marriage. **`WeddingClothingPay`**: fee for the wedding clothes.
* **`Society`**: `true` = marriage fees go to the society account (qb-management / esx\_society).
* **`ClothingChange`**: `true` = couples can change into wedding clothes at the church.
* **`ItemUpdateType`**: how identity items are updated after a surname change. `"reload"` = the item is taken and given back with the new name. `"remove"` = the item is only taken. Choose the items with `IDCard`, `DriverCard`, `Temporary`, `LawyerPass`, `WeaponLicense` and their item names.
* **`MarriedNotifyVisible`**: a server-wide "just married" notification.
* **`Adversting`** / **`AdverstingHours`**: a marriage advert shown to every player every X hours.
#### 3.3. Rings, Proposal & Delivery
* **`NeedTwoRing`** (ring mode):
* `false` (default), **set mode**: sets like "King & Princess" are sold in `/buyring`. One `weddingring` item is delivered, and when the proposal is accepted each spouse automatically gets the matching ring of the set.
* `true`, **individual ring mode**: rings are sold one by one. Both players need a ring for the proposal, and each spouse wears the ring they have.
* **Ring sets, metals and prices**: `RingSets`, `RingVariants` and `RingSystem` in `shared/outfits.lua`.
* **`RingSetAccount`**: the account the ring is paid from: `"bank"` or `"cash"`.
* **`UseRing`**: `true` = using the wedding ring after the wedding marks your spouse on the map.
* **`RingDrone`**: `method = "both"` (the player chooses), `"car"` (courier van only) or `"drone"` (drone only).
* **`RingOrderCooldown`**: extra wait (in seconds) between two ring orders. `0` = off.
* **`ClosedBoxOnDelivery`**: the courier / drone brings a closed ring box.
* **`SmartRing`**: sells the Smart Ring option in the shop when uniqers-smartring is on the server.
* **`ProposalMessage`** (`shared/venues.lua`): the proposal message on/off and its maximum length.
* **`ProposalTimeout`** (`shared/venues.lua`): seconds the other player has to answer a proposal (default `25`).
#### 3.4. Spouse Tracking & HUD
* **`SpouseBlipVisible`**: shows your spouse on the map.
* **`BlipType`**:
* `"normal"` (recommended, best for big servers): the blip is drawn on your own game while your spouse is within 500 m. No server load.
* `"hard"`: the server sends your spouse's position every few seconds at any distance (more server load).
* **`SpouseTopEmojiVisible`** / **`SpouseTopEmoji`**: the emoji above your spouse's head.
#### 3.5. Grand Ceremony & Venues (`shared/venues.lua`)
Venues are created in game with `/ceremonyadmin` and saved in the database; you don't edit this file to add a venue. The main settings are in `UniqersMarriage.Ceremony`:
* **`Commands`**: names of the ceremony commands.
* **`UseConfigVenue`**: while no venue exists yet, the old ceremony location from `shared/config.lua` (`CeremonyData`, `CeremonyFee`) is offered as a venue.
* **`Booking`**: paying account, ceremony length, calendar hours, how far ahead couples can book, refund percentages on cancel and no-show, and the announcement time.
* **`Timing`** / **`Distances`**: how long each step of the ceremony can take and the ranges used.
* **`Priest`**: the NPC priest model and the name printed on the marriage certificate.
* **`Effects`**: effect types and fireworks.
* **`Music`**: xsound settings and preset songs (YouTube links only). **`SpeakerProp`** / **`PartyLights`**: speaker stands and party lights.
* **`Invitations`**: the invitation item, the maximum number of guests and the answer time.
* **`Album`**: maximum photos per couple, caption length and photo cooldown.
**Wedding Car Rental** (`WeddingCars` in `shared/config.lua`): which cars can be rented, their rent and deposit, the paying account and the number plate. `RequireCeremony = true` means only couples with a booked ceremony can rent.
#### 3.6. Loyalty & Weekly Leaderboard (`shared/loyalty.lua`)
* **`LoyaltySystemEnabled`**: turns the daily / weekly couple missions on or off.
* **`WeeklyResetDay`** (1 = Monday ... 7 = Sunday), **`WeeklyResetHour`** and **`WeeklyResetMinute`**: the exact server time (24h) the leaderboard is reset and the rewards are given. Example: `6`, `19`, `34` = every Saturday at 19:34.
* **`WeeklyRankedRewards`**: the rewards (cash, items, vehicles) for the top 10 couples every week.
* **`Missions`**: legal and illegal, daily and one-time missions.
* **`PoliceAlert`**: the police jobs that are alerted during illegal missions.
#### 3.7. Valentine's Event, Love Scenes & Photos
* **`LoveScenes`** (`shared/valentines.lua`): the price of each love scene. `0` = free; remove a line to take that scene out of the menu.
* **`ValentineEvent`** (`shared/valentines.lua`):
* `UseDates = true`: the event opens by itself every year between `StartDate` and `EndDate` (month-day).
* `Active = true`: forces the event on regardless of the date (for testing or a special weekend).
* `Reward` and `DurationHours`: the reward for each spouse and the time a couple has to finish the tasks.
* **`UploadMethod`** (`shared/config.lua`): where in-game photos are uploaded: `"FiveManage"` (recommended; put your own token in `FiveManageToken`) or `"Discord"` (uses `DiscordWebhook`; Discord image links stop working after about a day).
#### 3.8. Married List Rewards
* **`BadgeRewards`**: the money couples receive for each anniversary badge (1, 3, 6 and 12 months), claimed in `/marriedpanel`.
#### 3.9. Staff & Permissions
A player counts as staff when any of these match:
* **`StaffPermissionNames`**: framework groups (for example `"admin"`, `"superadmin"`).
* **`StaffAcePermissions`**: ACE permissions (`"command"` is the standard txAdmin admin ace).
* **`StaffIdentifiers`**: identifiers that are always staff (`license:`, `discord:`, `steam:`), even if your framework permissions break.
Use `/marriagepermcheck` in game to see which check matched for you.
#### 3.10. Marriage Hub (`shared/hub.lua`)
* **`Command`** / **`Key`**: the hub command and an optional hotkey (for example `"F6"`). Players can rebind the key in Settings > Key Bindings > FiveM.
* **`MarriageImage`** / **`CardImages`** / **`LoyaltyHoverImage`**: the pictures on the hub cards.
* **`AllowBookingFromHub`**: `true` = couples can book their ceremony from the hub too.
* **`Cards`**: hide single cards for everyone.
#### 3.11. Logs & Debug
* **`ActiveDiscordLogs`** / **`DiscordWebhook`**: Discord logs.
* **`Debug`**: the master switch for console output. Keep it `false` on a live server; `true` prints diagnostics.
* **`AnimDebug`**: ring and animation diagnostics only.
#### 3.12. Languages
The language is chosen with `Locale` in `shared/config.lua`. The texts are in `shared/locales/` (en, tr, de, fr, es, pt, ru). If a language misses a text, the English one is used automatically.
**To add a new language:** copy `shared/locales/en.lua` (for example to `it.lua`), change `UniqersMarriage.Locales["en"]` to `UniqersMarriage.Locales["it"]`, translate the values (keep the keys the same), add the file to `fxmanifest.lua` next to the other language files and set `UniqersMarriage.Locale = "it"`.
***
### ⌨️ 4. Commands Reference
Command names can be changed in `shared/commands.lua` (the hub command in `shared/hub.lua`, the ceremony commands in `shared/venues.lua`).
| Command | Who | What it does |
| -------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/marriagehub` | Everyone | Opens the Marriage Hub (a hotkey can be set in `shared/hub.lua`) |
| `/buyring` | Everyone | Opens the ring shop |
| `/marriedpanel` | Everyone | Married couples list and anniversary rewards |
| `/loyaltymission` | Everyone | Loyalty missions menu |
| `/loyalty` | Everyone | Weekly loyalty leaderboard |
| `/lovemessage` | Engaged / married players | Sends a love scene to your partner |
| `/valentines` | Married players | Valentine's event tasks (while the event runs) |
| `/togglevalhud` | Everyone | Shows / hides the Valentine's HUD |
| `/showspouseemoji` | Everyone | Shows / hides the heart above your spouse |
| `/showuiwedding` / `/offuiwedding` | Everyone | Shows / hides the marriage mini HUD |
| `/edituiwedding` / `/resetuiwedding` | Everyone | Moves the mini HUD / puts it back in place |
| `/putthering` / `/puttheringoff` | Engaged / married players | Puts your wedding ring on / takes it off |
| `/ceremonypanel` | The couple | Ceremony panel: booking, invitations, guest list, album |
| `/ceremonymusic` | The couple | Music (DJ) panel of your ceremony |
| `/marriage [id1] [id2] [style] [surname]` | Priest / staff | Marries two engaged players. Style: `normal` (names stay), `takesurname` (the second player takes the first player's surname) or `custom` (both take the surname you write) |
| `/divorce [id1] [id2]` | Priest / staff | Divorces two players |
| `/breakengagement [id1] [id2]` | Priest / staff | Ends an engagement |
| `/priestpanel` | Priest / staff | Opens the priest panel |
| `/marriedadmin` | Staff | Marriage admin panel |
| `/multimarried` | Staff | Multiple marriage panel |
| `/givering [id] [setId] [variantId] [glow] [side]` | Staff | Gives a player a specific ring (see RING\_SETS.md) |
| `/ceremonyadmin` | Staff | Ceremony venue manager and editor |
| `/ceremonystart [id]` | Staff | Starts a booked ceremony right now |
| `/marriagesmartring [id] [1/0]` | Staff / console | Turns the smart wedding ring on / off for a couple |
| `/marriagepermcheck [id]` | Everyone | Shows which staff check matched (staff can check another player) |
`/lovemessage` and `/valentines` have fixed names.
***
### 💒 5. How It Works (Player Flow)
1. **Buy a ring:** `/buyring` > pick a set, a metal and glow > choose courier van or drone delivery.
2. **Propose:** use the `weddingring` item, choose the player and write your message. They have 25 seconds to answer. When they say yes, the couple is engaged and the rings go on their fingers.
3. **Apply at the church:** the engaged couple applies for marriage at the priest (an NPC or a player priest) and pays the fee. The documents are ready after `PreparationTime`.
4. **Organize the ceremony:** at the priest (Application Status > Organize a Ceremony) the couple picks a venue on the map, a date and a time. In `/ceremonypanel` they design invitations, invite guests, choose music and take photos; a wedding car can be rented at the priest. A priest can also marry the couple directly with `/marriage`.
5. **The ceremony:** the couple walks down the aisle, listens to the priest, says the vows and signs the marriage certificate. Now they are married: the chosen surname and the ID items are updated, and each spouse receives a `weddingcertificate`.
6. **Married life:** anniversary rewards in `/marriedpanel`, loyalty missions and the weekly leaderboard, love scenes, the wedding album and the Valentine's event, all reachable from `/marriagehub`.
7. **Divorce:** a spouse files a divorce petition at the priest (see `ConsensualDivorce`).
***
### 🚨 6. Developer API
#### 6.1. CK (Character Kill) Integration
If your server uses a Permadeath (CK) or Character Deletion script, dead characters must be removed from the marriage database. Place this trigger inside your Multicharacter or CK script (server side), right where the character is deleted from the database:
```lua
-- Replace 'citizenid' with the actual variable holding the deleted character's identifier.
local citizenid = "DELETED_CHARACTER_ID"
TriggerEvent('uniqers-marriage:CharacterDeleted', citizenid)
```
This automatically moves the deleted character to the `uniqers_marriage_cklist` table. Server admins can then open the `/marriedadmin` panel in game to view and cleanly wipe these marriages with one click.
#### 6.2. Marriage Info (server export)
```lua
local info = exports['uniqers-marriage']:GetMarriageInfo(source)
if info then
print(info.engaged) -- true while engaged, false when married
print(info.spouseId) -- spouse's citizenid / identifier
print(info.spouseName) -- spouse's name
print(info.spouseSrc) -- spouse's server id when online, otherwise nil
print(info.since) -- date of the marriage (or engagement)
print(info.days) -- days since that date
print(info.setId, info.variantId, info.glow) -- the wedding ring they wear
end
-- info is nil when the player is single
```
#### 6.3. Ring Guard (for clothing scripts)
The wedding rings sit in a normal clothing slot. Add this one line to your clothing script's **save** event, right before it writes the outfit to the database, and save what comes back. A ring the player doesn't own is removed from the outfit:
```lua
skin = exports['uniqers-marriage']:FilterRingOutfit(src, skin, model)
-- model is optional: ped model or "male" / "female", only needed when the outfit doesn't carry it
```
Other server exports:
| Export | Returns |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `IsRingAllowed(src, componentId, drawable, texture)` | `true` / `false` for a single component |
| `FilterRingComponent(src, componentId, drawable, texture)` | `ok, drawable, texture` (the values to use instead when `ok` is `false`) |
| `GetPlayerRing(src)` | The ring the player may wear: `{ setId, variantId, glow, gender, drawable, texture, isDefault }` or `nil` |
| `IsRingDrawable(drawable, gender)` | `true` when the drawable is a wedding ring |
| `GetRingDrawables()` | Every ring drawable per gender |
| `GetRingComponentId()` | The clothing slot the rings use |
Client exports: `GetMyRing()`, `IsRingAllowedLocal(componentId, drawable, texture)`, `IsRingDrawable(drawable, gender)`, `GetRingDrawables()`, `GetRingComponentId()`.
***
### ❓ 7. Troubleshooting
* **"Framework could not be found automatically"** in the console: start the script after your framework (see 2.5) or set `Framework` by hand.
* **"did not return a core object. On QBox enable the qb-core bridge in qbx\_core"**: enable the qb-core bridge in qbx\_core.
* **`attempt to call a nil value (field 'SetNameLast')`**: the core modification in 2.4 is missing.
* **SQL error "Illegal mix of collations"**: see the collation check in 2.2.
* **The wedding invitation can't be used**: add the `weddinginvitation` item (2.3).
* **Photos don't work (album, Valentine's task)**: `screenshot-basic` must be started, and `FiveManageToken` (or `DiscordWebhook`) must be set.
* **No music at the ceremony**: start `xsound`. Only YouTube links work.
* **The ring shows up as another clothing item**: set `DrawableBase` (RING\_SETS.md > Common problems).
* **A text is missing or a notification is empty**: a key is missing in your language file. Compare it with `shared/locales/en.lua`.
* **You need more details**: set `UniqersMarriage.Debug = true` and check the F8 / server console.
Still stuck? Open a ticket on our Discord:
***
## Support & Updates & Questions
