# uniqers-marriage
## 💍 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 massive roleplay enhancement system designed for your FiveM server. It includes dynamic surname changes, a couple's Loyalty (mission) system, weekly leaderboards with automated rewards, a seasonal Valentine's Day event, and a fully functional Priest job.
***
### 🌟 1. Key Features
* Multi-Framework Support: Fully compatible with QBCore, Qbox, ESX (Old/New), and custom frameworks.
* Advanced Interaction: Supports `ox_target`, `qb-target`, or traditional `DrawText 3D`.
* Dynamic Surname & Metadata Updates: Couples can take their spouse's surname or create a custom one. The script automatically updates the database, overhead names, and re-issues identity items (ID Card, Driver's License) with the new metadata.
* Loyalty System (Missions): Couples can earn points by completing Legal (buying gifts, romantic emotes) and Illegal (co-op store robberies, luxury car thefts with hacking mini-games) missions together.
* Weekly Leaderboards & Rewards: Automated weekly resets. Top-ranked 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 (taking photos via FiveManage/Discord webhook, drinking wine, gifting) to earn massive rewards.
* Priest Job System: A complete progression system for Priests with XP, levels, and payouts. Priests manage marriage applications, spawn church vehicles, and perform ceremonies. (Can also run 100% via NPCs).
* Spouse Tracking: Use the wedding ring to place a live GPS blip on your partner, or see a floating 3D Heart Emoji above their head when close.
***
### 🛠️ 2. Installation Guide
#### 2.1. Dependencies
Before starting, ensure you have the following installed on your server:
* [PolyZone](https://github.com/mkafrin/PolyZone/releases): Required for interaction zones.
* screenshot-basic: Required for the Valentine's Day photo task.
* ox\_target / qb-target: (Optional) If you choose to use the target system instead of DrawText.
#### 2.2. Database Setup
1. Import the provided `uniqers-marriage-database.sql` file into your database.
2. ⚠️ CRITICAL COLLATION CHECK: Ensure the collation of the `owner` and `married` columns in the `uniqers_marriage` tables matches the exact collation of your main framework's identifier column (e.g., `citizenid` in QBCore or `identifier` in ESX).
* *Example:* If your `players` table uses `utf8mb4_unicode_ci`, set the marriage columns to `utf8mb4_unicode_ci` as well to prevent SQL syntax errors.
#### 2.3. Adding Items
Add the item images (`weddingring.png`, `weddingcertificate.png`, `loyaltycard.png`) to your inventory's image folder, then add the item codes:
For QBCore (New) - `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 :)'},
```
For OX\_Inventory - `ox_inventory/data/items.lua`:
Lua
```
["weddingring"] = { label = "Wedding Ring", weight = 10, stack = true, close = true },
["weddingcertificate"] = { label = "Wedding Certificate", weight = 10, stack = true, close = true },
["loyaltycard"] = { label = "Loyalty Card", weight = 10, stack = true, 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);
```
#### 2.4. Core Modification (QBCore / Qbox ONLY)
To allow the script to instantly update a player's first and last name after a marriage/divorce, you must add helper functions to your core.
Open `qb-core/server/player.lua`, locate the `self.Functions.SetPlayerData` function, and paste this directly above it:
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
```
#### 2.5. Server.cfg Start Order
Ensure the script is started *after* your framework and target scripts:
Plaintext
```
# QBCore
ensure qb-target
ensure uniqers-marriage
# ESX
ensure ox_lib
ensure ox_target
ensure uniqers-marriage
```
***
### ⚙️ 3. Configuration (config.lua) Breakdown
The `config.lua` is highly detailed. Below is an explanation of the key sections.
#### Framework & Core Settings
* `DatabaseSelect`: Choose your SQL wrapper (`"oxmysql"`, `"mysql-async"`, etc.).
* `Framework`: Your server's framework (`"qbcore"`, `"esx"`, etc.).
* `Notify`: Choose your notification system (`"uniqers-notify"`, `"qbcore"`, `"esx"`).
* `Clothes`: Select your clothing script to allow couples to automatically change into wedding attire (`"qb-clothing"`, `"illenum-apperance"`, `"esx-skinchanger"`, etc.).
#### Mechanics & Gameplay
* `NPCFunction`: If `"yes"`, players can interact with NPC Priests. If `"no"`, players must rely on real players with the Priest job.
* `ConsensualDivorce`: If `"yes"`, you can only divorce if your spouse is online and standing next to you. If `"no"`, you can divorce unilaterally.
* `NeedTwoRing`: If `true`, both players need a ring item in their inventory to marry.
* `PreparationTime`: Wait time (in minutes) for marriage documents to be prepared.
#### Economy
* `WeddingPay`: Fee to apply for marriage.
* `WeddingClothingPay`: Fee to rent wedding clothes.
* `RingPay`: Fee to order a ring via the delivery NPC.
* `Society`: If `true`, marriage fees go to the priest job's society fund.
#### Visuals & Blips
* `SpouseBlipVisible`: Toggles the GPS map tracker for spouses.
* `BlipType`: `"hard"` (optimized interval updates for high-pop servers) or `"normal"`.
* `SpouseTopEmojiVisible`: Shows a floating 3D emoji above your partner's head.
#### Advanced Systems (Loyalty & Valentine)
* `LoyaltySystemEnabled`: Toggles the daily/weekly couple missions.
* `WeeklyResetDay` & `WeeklyResetHour`: Sets the exact time the leaderboard wipes and distributes rewards.
* `WeeklyRankedRewards`: Customize the loot (Cash, Items, Vehicles) given to the Top 10 couples every week.
* `ValentineEvent.Active`: Toggles the Valentine's Day task UI and rewards.
* `UploadMethod`: Choose `"FiveManage"` or `"Discord"` for hosting in-game polaroid photos.
***
### ⌨️ 4. Commands Reference
All commands can be renamed in `config.lua`.
| **Command** | **Permission** | **Description** |
| ------------------ | -------------- | ----------------------------------------------------------------------------- |
| `/loyaltymission` | All Players | Opens the Couple's Loyalty Missions UI. |
| `/loyalty` | All Players | Opens the Weekly Leaderboard & Rewards UI. |
| `/valentines` | All Players | Opens the Valentine's Day event panel. |
| `/togglevalhud` | All Players | Toggles the Valentine's HUD on/off. |
| `/showspouseemoji` | All Players | Toggles the floating 3D heart over your spouse. |
| `/putthering` | All Players | Plays the ring equip animation and updates clothing. |
| `/buyring` | All Players | Opens the Ring Delivery NPC purchase menu. |
| `/marriage` | Admin/Priest | Marries two players (Requires IDs and Surname Style). |
| `/divorce` | Admin/Priest | Divorces two players. |
| `/breakengagement` | Admin/Priest | Breaks off an engagement. |
| `/priestpanel` | Admin/Priest | Opens the Priest UI to accept/deny marriage applications. |
| `/marriedadmin` | Admin | Opens the Admin UI to manage all server marriages, engagements, and CK lists. |
***
### 🚨 5. Developer API / CK (Character Kill) Integration
If your server uses a Permadeath (CK) or Character Deletion script, you need to ensure dead characters are removed from the marriage database.
Place this trigger inside your Multicharacter or CK script 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 corrupted marriages with one click.
***
Support & Updates:
Encountered a bug or need help configuring a custom framework? Join our community!
## Support & Updates & Questions
\
---
# 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://uniqers-scripts-docs.gitbook.io/uniqers-scripts-docs/uniqers-marriage.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.