Skip to content

Commit e633184

Browse files
SekulDevSekulDev
committed
feat(vzn-cleanerjob): add docs for this script
1 parent 45c9478 commit e633184

5 files changed

Lines changed: 348 additions & 1 deletion

File tree

‎pages/_meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
22
"index": "Introduction",
3-
"vzn-notify": "vzn-notify"
3+
"vzn-notify": "VZN Notify",
4+
"vzn-cleanerjob": "VZN Cleanerjob"
45
}

‎pages/vzn-cleanerjob.mdx‎

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

‎pages/vzn-cleanerjob/_meta.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"config": "Configuration",
3+
"framework": "Framework"
4+
}

‎pages/vzn-cleanerjob/config.mdx‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Config
2+
3+
### LOCALES
4+
5+
- This script is using ox_lib locales. You can edit values 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+
7+
### LOGS
8+
9+
To Configure logs go to `config_server.lua` and put here your discord webhook
10+
11+
- if you want to edit logs logic go to `server/editable/functions.lua` on function called `SendLog`
12+
13+
```lua filename="config.lua"
14+
-- your wehbhook where logs will be sent
15+
---@type string
16+
SConfig.LogWebhook = "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+
### JOB NAME
39+
40+
if you want to change job name required to do job change it in `config.lua`
41+
42+
```lua filename="config.lua"
43+
--- job name that player needs have to use job (remember to add job to db for ESX or to jobs.lua for QBCore)
44+
---@type string
45+
Config.JobName = "cleaner"
46+
```
47+
48+
### SALARY METHOD
49+
50+
- If player should earn money in cash, set this field to `cash` (ESX too, not money)
51+
- If player should earn money in bank account, set this field to `bank`
52+
53+
```lua filename="config.lua"
54+
--- in which method player will be getting salary for job
55+
---@type 'cash' | 'bank'
56+
Config.SalaryMethod = "cash"
57+
```
58+
59+
### START JOB COORDS
60+
61+
- pedModel: `string` | `number` model / hash of ped
62+
- pedCoords: `vector3` location where ped is and target action to start job
63+
- pedHeading: `number` heading of ped
64+
- vehiclesSpawnPoints `vector4[]` points where vehicles will be spawn (if first is busy, vehicle will be spawned on second etc)
65+
66+
```lua filename="config.lua"
67+
Config.StartJob = {
68+
pedModel = "cs_bankman",
69+
pedCoords = vec3(1231.49, -1083.04, 38.51),
70+
pedHeading = 127.5,
71+
vehiclesSpawnPoints = {
72+
vec4(1217.81, -1070.94, 39.32, 124.72),
73+
vec4(1213.85, -1067.93, 39.65, 119.05),
74+
vec4(1210.49, -1064.28, 40.01, 124.72),
75+
vec4(1206.93, -1060.80, 40.43, 119.05),
76+
vec4(1202.59, -1057.70, 40.90, 124.72),
77+
vec4(1197.27, -1055.20, 41.39, 121.88),
78+
},
79+
}
80+
```
81+
82+
### BONUS FOR WORK WITH FRIEND
83+
84+
- money: `number` multiplier how much player earn more money for work with friend
85+
- xp: `number` multiplier how much player earn more xp for work with friend
86+
- you can edit bonus logic in `server/editable/functions.lua` in function called `WorkWithFriendBonus`
87+
88+
```lua filename="config.lua"
89+
--- multipliers of amounts if player work with friend
90+
Config.WorkWithFriendBonus = {
91+
money = 1.15,
92+
xp = 1.10,
93+
}
94+
```
95+
96+
### CLOTHES
97+
98+
- enabled: `boolean` you can disable changing clothes here
99+
- male: `table` clothes for male
100+
- female: `table` clothes for female
101+
102+
```lua filename="config.lua"
103+
Config.Clothes = {
104+
enabled = true, -- if you set it to false, player clothes won't change in job,
105+
male = {
106+
['arms'] = 0,
107+
['tshirt_1'] = 15,
108+
['tshirt_2'] = 0,
109+
['torso_1'] = 86,
110+
['torso_2'] = 0,
111+
['pants_1'] = 10,
112+
['pants_2'] = 2,
113+
},
114+
female = {
115+
['arms'] = 0,
116+
['tshirt_1'] = 15,
117+
['tshirt_2'] = 0,
118+
['torso_1'] = 86,
119+
['torso_2'] = 0,
120+
['pants_1'] = 10,
121+
['pants_2'] = 2,
122+
},
123+
}
124+
```
125+
126+
### PAVEMENT CLEANING
127+
128+
- minXP: `number` minimum xp player need to work in this type
129+
- type: `"pavementCleaning"` dont change
130+
- data: `table`
131+
- addXP: `number` how much xp player will earn after complete job
132+
- vehicle: `number` | `string` vehicle model
133+
- locations: `table[]`
134+
- money: `number` payment for player if complete this location
135+
- gpsDestination: `vector3`
136+
- points: `table[]`
137+
- coords: `vector3`
138+
- cleaningDuration: `number` time of progressbar cleaning this points
139+
- props: `table[]` you can add multiple props in one point to make stash of trash etc
140+
- offset: `vector3` offset from point coords of this prop
141+
- heading: `number` heading of prop
142+
- model: `string` | `number` model of prop
143+
144+
### APARTMENT CLEANING
145+
146+
- minXP: `number` minimum xp player need to work in this type
147+
- type: `"apartmentCleaning"` dont change
148+
- data: `table`
149+
- addXP: `number` how much xp player will earn after complete job
150+
- vehicle: `number` | `string` vehicle model
151+
- locations: `table[]`
152+
- money: `number` payment for player if complete this location
153+
- gpsDestination: `vector3`
154+
- insideCoords = `vector3` coords where player will be teleported,
155+
- points: `table[]`
156+
- coords: `vector3`
157+
- cleaningDuration: `number` time of progressbar cleaning this points
158+
- props: `table[]` you can add multiple props in one point to make stash of trash etc
159+
- offset: `vector3` offset from point coords of this prop
160+
- rotation: `vector3` rotation of prop
161+
- heading: `number` heading of prop
162+
- model: `string` | `number` model of prop
163+
164+
### ROAD CLEANING
165+
166+
- minXP: `number` minimum xp player need to work in this type
167+
- type: `"roadCleaning"` dont change
168+
- data: `table`
169+
- addXP: `number` how much xp player will earn after complete job
170+
- vehicle: `number` | `string` vehicle model
171+
- locations: `table[]`
172+
- money: `number` payment for player if complete this location
173+
- gpsDestination: `vector3`
174+
- speedLimitWhileCleaning: `number` in meters/second (if you want to disable it, set it to -1)
175+
- points: `table[]`
176+
- coords: `vector3`
177+
178+
### OTHER
179+
180+
If you want to edit other logic of script, all open sourced functions is in `client/editable/**`, `server/editable/**` and `bridge/**/*`

‎pages/vzn-cleanerjob/framework.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
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 CLIENT
14+
15+
If you wanna edit this functions you can do it. If you want to use custom frameworks, do similar logic in `bridge/custom/client.lua` using your framework functions
16+
17+
```lua filename="bridge/custom/client.lua"
18+
19+
--- getting framework object
20+
FRAMEWORK = exports['your_framework']['export_name']()
21+
22+
--- load script if player is loaded when script started
23+
Citizen.CreateThread(function()
24+
if FRAMEWORK.IsPlayerLoaded() then
25+
OnPlayerLoad()
26+
end
27+
end)
28+
29+
--- load player on load
30+
RegisterNetEvent("yourFramework:onPlayerLoad", function()
31+
OnPlayerLoad()
32+
end)
33+
34+
--- refresh job blips on playerData job change
35+
AddEventHandler('yourFramework::onJobChange', function()
36+
RefreshJobBlips()
37+
end)
38+
39+
--- checking if player can work, you can edit it how you want (for example disable job based logic)
40+
---@return boolean
41+
function CanWork()
42+
return FRAMEWORK.GetPlayerJob() == Config.JobName
43+
end
44+
45+
--- change clothes logic
46+
local lastClothes = nil
47+
function ChangeClothes(work)
48+
if not Config.Clothes.enabled then return end
49+
50+
if work then
51+
local gender = FRAMEWORK.GetPlayerGender() -- male or female
52+
local clothes = work and Config.Clothes[gender] or lastClothes
53+
if not clothes then return end
54+
lastClothes = FRAMEWORK.GetPlayerSkin()
55+
TriggerEvent('yourFramework:changeClothes', clothes)
56+
else
57+
TriggerEvent('yourFramework:changeClothes', lastClothes)
58+
lastClothes = nil
59+
end
60+
end
61+
```
62+
63+
### CUSTOM SERVER
64+
65+
If you wanna edit this functions you can do it. If you want to use custom frameworks, do similar logic in `bridge/custom/server.lua` using your framework functions
66+
67+
```lua filename="bridge/custom/server.lua"
68+
69+
--- getting framework object
70+
FRAMEWORK = exports['your_framework']['export_name']()
71+
72+
---@class PlayerJob
73+
---@field name string unique name of the job
74+
---@field label string
75+
76+
---@class Player
77+
---@field source number id of player
78+
---@field identifier string unique identifier of player to using it in db
79+
---@field job PlayerJob
80+
---@field addMoney fun(amount: number) adding money after job complete
81+
82+
--- returning Player object from id
83+
---@param playerId number
84+
---@return Player | nil
85+
function GetPlayerFromId(playerId)
86+
local frameworkPlayer = FRAMEWORK.GetPlayer(playerId)
87+
if not frameworkPlayer then return end
88+
89+
---@type Player
90+
local player = {
91+
source = playerId,
92+
identifier = frameworkPlayer.getCharacterUniqueId(),
93+
job = {
94+
name = frameworkPlayer.job.name,
95+
label = frameworkPlayer.job.label,
96+
},
97+
addMoney = function(amount)
98+
local method = Config.SalaryMethod
99+
if method == "cash" then
100+
---@diagnostic disable-next-line
101+
method = "money"
102+
end
103+
104+
frameworkPlayer.addMoney(method, amount)
105+
end,
106+
}
107+
108+
return player
109+
end
110+
111+
--- checking if player can work, you can edit it how you want (for example disable job based logic)
112+
---@param player Player
113+
---@return boolean
114+
function CanPlayerWork(player)
115+
return player.job.name == Config.JobName
116+
end
117+
118+
MySQL.ready(function()
119+
if not FRAMEWORK.IsJobExisting(Config.JobName) then
120+
lib.print.error(string.format("`%s` job doesnt exists!! Add this job in your framework", Config.JobName))
121+
end
122+
end)
123+
124+
```

0 commit comments

Comments
 (0)