Skip to content

Commit 701649d

Browse files
SekulDevSekulDev
committed
feat(vzn-references): finish docs to this script
1 parent 6338b0d commit 701649d

6 files changed

Lines changed: 260 additions & 0 deletions

File tree

‎pages/_meta.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@ export default {
22
index: "Introduction",
33
"vzn-notify": "VZN Notify",
44
"vzn-cleanerjob": "VZN Cleanerjob",
5+
"vzn-references": "VZN References",
56
};

‎pages/vzn-references.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { Steps } from "nextra/components";
2+
3+
# VZN-REFERENCES
4+
5+
References system that, rewards players who invite friends
6+
7+
<iframe
8+
className="aspect-video w-full"
9+
src={"https://www.youtube.com/embed/TODO"}
10+
title="VZN Cleanerjob preview"
11+
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
12+
></iframe>
13+
14+
[PURCHASE](https://vzn-scripts.tebex.io)
15+
16+
## Requirements
17+
18+
- oxmysql
19+
- ox_lib
20+
21+
## Installation
22+
23+
<Steps>
24+
### Download the newest version from [Keymaster](https://keymaster.fivem.net/asset-grants)
25+
26+
### Put vzn-references in your server resources folder
27+
28+
### Add `ensure vzn-references` to your server.cfg
29+
30+
</Steps>
31+
32+
## Compatibility
33+
34+
- [esx](https://github.com/esx-framework/esx_core)
35+
- [qb-core](https://github.com/qbcore-framework/qb-core)
36+
- Or you can integrate this script with your framework if you can

‎pages/vzn-references/_meta.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
export default {
2+
config: "Configuration",
3+
framework: "Framework",
4+
custom_reward: "Custom Reward",
5+
};

‎pages/vzn-references/config.mdx‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Config
2+
3+
### LOCALES
4+
5+
- You can translate this script in every language, which you want in `locales/*.json*`. If you add your language, you can send it us in our discord and we will add it to our script
6+
- To configure which json file will be loaded as locales go to `config.lua` and set field `Config.Locales` to name of your file
7+
8+
### LOGS
9+
10+
To configure logs go to `s_config.lua` and put here your discord webhook
11+
12+
- if you want to edit logs logic go to `server/editable/editable_logs.lua`
13+
14+
```lua filename="s_config.lua"
15+
---@type string
16+
SConfig.Webhook = 'your_webhook_here'
17+
```
18+
19+
### FRAMEWORK NAMES
20+
21+
```lua filename="config.lua"
22+
--- If you have custom name of exports / resourceName, change it here to script can works correctly.
23+
--- If you wanna connect your custom framework look at bridge/custom/*.lua.
24+
--- If you wanna edit your framework functions etc look at bridge/your_framework/*.lua
25+
---@type table<string, {resourceName: string, export: string}>
26+
Config.Framework = {
27+
ESX = {
28+
resourceName = "es_extended",
29+
export = "getSharedObject",
30+
},
31+
QB = {
32+
resourceName = "qb-core",
33+
export = "GetCoreObject",
34+
},
35+
}
36+
```
37+
38+
### COMMAND
39+
40+
To configure command name, which will opening rewards for invitations menu you can do it in `config.lua` in field called `Config.ReferencesCommand`
41+
42+
```lua filename="config.lua"
43+
---@type string
44+
Config.ReferencesCommand = 'references'
45+
```
46+
47+
### REWARDS PER INVITE
48+
49+
The most important thing in this config is rewards. In this table, key is how many invites player need to claim this reward. If you wanna to give other rewards than items you can set custom type of them and implement giving them in `bridge/your_framework/server.lua` in function called `AddReward`
50+
51+
```lua filename="config.lua"
52+
---@class ItemReward
53+
---@field name string
54+
---@field count number
55+
---@field type 'item'
56+
57+
---@class OtherReward
58+
---@field name string
59+
---@field count number
60+
---@field type string
61+
---@field label string
62+
---@field image string
63+
64+
---@alias ConfigReward ItemReward | OtherReward
65+
66+
67+
---@type table<number, ConfigReward> key is invited count, value is reward data
68+
Config.Rewards = {
69+
[1] = {
70+
name = 'burger',
71+
count = 3,
72+
type = 'item'
73+
},
74+
[2] = {
75+
name = 'money',
76+
count = 500,
77+
type = 'item'
78+
},
79+
[3] = {
80+
name = 'burger',
81+
count = 5,
82+
type = 'item'
83+
},
84+
[4] = {
85+
name = 'burger',
86+
count = 5,
87+
type = 'item'
88+
},
89+
[5] = {
90+
name = 'ammo-9',
91+
count = 20,
92+
type = 'item'
93+
},
94+
[6] = {
95+
name = 'burger',
96+
count = 5,
97+
type = 'item'
98+
},
99+
[7] = {
100+
name = 'burger',
101+
count = 5,
102+
type = 'item'
103+
},
104+
[8] = {
105+
name = 'WEAPON_PISTOL',
106+
count = 1,
107+
type = 'item'
108+
},
109+
}
110+
```
111+
112+
### REWARDS FOR ENTER CODE
113+
114+
To encourage players to enter referral codes, when they enter a friend's code they also get rewards. You can configure these rewards here. Logic is the same as above
115+
116+
```lua filename="config.lua"
117+
---@type ConfigReward[] 3/4 elements should looks good
118+
Config.RewardsForEnterCode = {
119+
{
120+
name = 'burger',
121+
count = 5,
122+
type = 'item'
123+
},
124+
{
125+
name = 'money',
126+
count = 10000,
127+
type = 'item'
128+
},
129+
{
130+
name = 'WEAPON_KNIFE',
131+
count = 1,
132+
type = 'item'
133+
}
134+
}
135+
```

‎pages/vzn-references/custom_reward.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import { Steps } from "nextra/components";
2+
3+
# CUSTOM REWARD
4+
5+
Adding other rewards than items could be very wanted function. Of course our script is ready to do that
6+
7+
### CONFIG
8+
9+
<Steps>
10+
### Add in config reward with other type than item, for example car
11+
```lua copy
12+
Config.Rewards = {
13+
-- ...
14+
[10] = { -- reward for 10 invites
15+
name = 'zentorno',
16+
count = 1,
17+
type = 'car',
18+
-- !!! VERY IMPORTANT THAT CUSTOM REWARD MUST HAS THESE FIELDS BELOW !!!
19+
label = 'Zentorno',
20+
image = 'https://github.com/MericcaN41/gta5carimages/blob/main/images/zentorno.png?raw=true'
21+
},
22+
-- ...
23+
}
24+
```
25+
26+
### Go to `bridge/your_framework/server.lua` to function called `AddReward` and implement your giving this type of reward logic
27+
28+
```lua copy filename="bridge/*/server.lua"
29+
--- add reward for player
30+
---@param player Player
31+
---@param reward ConfigReward
32+
function AddReward(player, reward)
33+
if reward.type == 'item' then
34+
local esxPlayer = ESX.GetPlayerFromId(player.source)
35+
esxPlayer.addInventoryItem(reward.name, reward.count)
36+
37+
-- IMPLEMENT OUR TYPE FROM CONFIG ABOVE
38+
elseif reward.type == 'car' then
39+
40+
-- for example our function to giving car
41+
GiveCarForPlayer(player.identifier, reward.name)
42+
43+
else
44+
lib.print.warn('This type of reward is not implemented. Do it in vzn-references/bridge/esx/server.lua')
45+
--- implement it yourself
46+
end
47+
end
48+
```
49+
50+
</Steps>

‎pages/vzn-references/framework.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import { Callout } from "nextra/components";
2+
3+
# FRAMEWORK
4+
5+
### AUTO-DETECTION
6+
7+
<Callout type="info" emoji="ℹ️">
8+
The framework is auto-detected based on started resource. You can look at it `bridge/**`
9+
</Callout>
10+
11+
If you wanna edit framework functions go to `bridge/**/*.lua`
12+
13+
### CUSTOM FRAMEWORK
14+
15+
If you wanna make compatibility our script with your framework go to `bridge/custom/*.lua` and implement these functions like in examples
16+
17+
### OPEN ENTER CODE MENU
18+
19+
Default the enter code menu should open on create new character on your server. But implementation of this sometimes could be insufficient. If you wanna to enter code menu in other moment of server, or for example using command, go to `bridge/*/client.lua` and remove implementation of executing `enterCode` export.
20+
21+
To execute open enter menu (for example if your server has another creating character logic) use export below
22+
23+
```lua copy
24+
exports['vzn-references']:enterCode()
25+
```
26+
27+
### INVENTORY
28+
29+
The script has implemented default ESX/QB inventory and ox_inventory. If you wanna to implement other inventory, do it in these functions
30+
31+
- `client/editable/editable_functions.lua` : `GetImagePath()` - function returning path to items images (png files)
32+
- `bridge/*/server.lua` : `GetItemLabel(itemName)` - function returning label of item if exists
33+
- `bridge/*/server.lua` : `AddReward(player, reward)` - function giving reward to player, adding items logic etc

0 commit comments

Comments
 (0)