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 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: 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

https://discord.gg/MyrGhbf9tM