Skip to content

Commit d6b530c

Browse files
antond15antond15
authored
feat(scoreboard): v2 docs (#5)
1 parent 6ccabeb commit d6b530c

File tree

11 files changed

+386
-5
lines changed

11 files changed

+386
-5
lines changed

‎index.css

+6
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,9 @@
88
display: flex;
99
margin-top: 0.5rem;
1010
}
11+
12+
.ac-splitter {
13+
margin-top: 2rem;
14+
margin-bottom: 2rem;
15+
border-top-width: 3px;
16+
}

‎pages/_meta.json

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
{
22
"index": "Home",
3-
"radio": "ac_radio",
4-
"documents": "ac_documents",
5-
"gifts": "ac_gifts",
3+
"radio": "AC Radio",
4+
"scoreboard": "AC Scoreboard",
5+
"documents": "AC Documents",
6+
"gifts": "AC Gifts",
67
"link_tebex": {
78
"title": "Tebex",
8-
"href": "https://ac-scripts.tebex.io/",
9+
"href": "https://store.acscripts.dev/",
910
"type": "page",
1011
"newWindow": true
1112
},

‎pages/scoreboard/_meta.json

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"index": "Introduction",
3+
"config": "Configuration",
4+
"guides": "Guides",
5+
"issues": "Common issues"
6+
}

‎pages/scoreboard/config.mdx

+201
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Configuration
2+
3+
4+
## settings \{ \}
5+
6+
### title
7+
Text and logo shown in the scoreboard header.
8+
9+
**Accepted values**
10+
text: `string`
11+
logo: `string` (URL to the image file)
12+
13+
---
14+
15+
### side
16+
On which side of the screen should the scoreboard be displayed.
17+
18+
**Accepted values**
19+
`string` → `'left'{:lua}` or `'right'{:lua}`
20+
21+
---
22+
23+
### showOverlay
24+
Enable showing background overlay when scoreboard is open.
25+
26+
**Accepted values**
27+
`boolean` (true / false)
28+
29+
---
30+
31+
### closeOnEscape
32+
Close scoreboard when the escape key is pressed.
33+
34+
**Accepted values**
35+
`boolean` (true / false)
36+
37+
---
38+
39+
### closeOnOutsideClick
40+
Close scoreboard when clicked outside of it.
41+
42+
**Accepted values**
43+
`boolean` (true / false)
44+
45+
---
46+
47+
### uppercaseNames
48+
Make all player names uppercase.
49+
50+
**Accepted values**
51+
`boolean` (true / false)
52+
53+
---
54+
55+
### highlightEmptyGroups
56+
Highlight empty groups by making the count number red.
57+
58+
**Accepted values**
59+
`boolean` (true / false)
60+
61+
---
62+
63+
### compactPlayers
64+
Change the player row height to be more compact.
65+
66+
**Accepted values**
67+
`boolean` (true / false)
68+
69+
---
70+
71+
### compactGroups
72+
Change the group row height to be more compact.
73+
74+
**Accepted values**
75+
`boolean` (true / false)
76+
77+
---
78+
79+
### playerColumns
80+
How many columns to use for player list.
81+
`2` columns will show 2 players per row, so it will be more compact.
82+
83+
**Accepted values**
84+
`number` → `1{:lua}` or `2{:lua}`
85+
86+
---
87+
88+
### groupColumns
89+
How many columns to use for group list.
90+
`2` columns will show 2 groups per row, so it will be more compact.
91+
92+
**Accepted values**
93+
`number` → `1{:lua}` or `2{:lua}`
94+
95+
96+
97+
<hr className="ac-splitter" />
98+
99+
100+
101+
## visibleSections \{ \}
102+
The following accepted values are valid for all options in this category.
103+
See the [guide](./guides/ace-sections) for more information on how to use ACE permissions.
104+
105+
**Accepted values**
106+
`true{:lua}`: Visible for everyone
107+
`false{:lua}`: Completely disabled and hidden for everyone
108+
`'limited'{:lua}`: Visible only for players with the required ACE permission
109+
110+
### groups
111+
Show or hide the groups section.
112+
113+
---
114+
115+
### players
116+
Show or hide the players section.
117+
118+
---
119+
120+
### playerNames
121+
Show or hide player names in the players section.
122+
Setting this to `false{:lua}` will change all player names to "**Anonymous player**".
123+
124+
---
125+
126+
### playerIds
127+
Show or hide player IDs in the players section.
128+
Setting this to `false{:lua}` will hide all player IDs.
129+
130+
---
131+
132+
### statusIndicators
133+
Show or hide the status indicators section.
134+
135+
---
136+
137+
### footer
138+
Show or hide the footer section.
139+
140+
141+
142+
<hr className="ac-splitter" />
143+
144+
145+
146+
## commandName
147+
Name of the command to open the scoreboard.
148+
149+
**Accepted values**
150+
`string`
151+
152+
153+
154+
## commandKey
155+
Default keybind for the radio command.
156+
157+
**Accepted values**
158+
`false{:lua}` = Keybind will not be created at all.
159+
`''{:lua}` = Empty quotes for creating the keybind, but not setting a default key.
160+
`'NUMPAD0'{:lua}` = Or any other [valid key](https://docs.fivem.net/docs/game-references/input-mapper-parameter-ids/keyboard) to create a keybind with *this* key as a default.
161+
162+
163+
164+
## includeOffDuty
165+
Include off-duty players in the group count.
166+
167+
**Accepted values**
168+
`boolean` (true / false)
169+
170+
171+
172+
## groups
173+
Individual group rows shown in scoreboard.
174+
175+
**Accepted values**
176+
`table[]` with the following structure:
177+
178+
```ts
179+
{
180+
label: string; // Name of the group row shown in scoreboard
181+
groups: string[]; // Array of groups to include in this row's total count
182+
}
183+
```
184+
185+
186+
187+
## statusIndicators
188+
Individual status indicators shown in the section.
189+
For more information on how to use custom icons, see the guide [here](./issues#status-indicator-icon-is-not-showing).
190+
To learn how to change the state of these indicators, see the guide [here](./guides/status-indicators).
191+
192+
**Accepted values**
193+
`table[]` with the following structure:
194+
195+
```ts
196+
{
197+
id: string; // Unique identifier for the status indicator, used in your exports to change the state
198+
label: string; // Label visible in the hover tooltip
199+
icon: string; // Icon of the indicator, must be a valid Iconify name
200+
defaultState?: boolean; // Default state of the indicator; true = on, false = off
201+
}

‎pages/scoreboard/guides/_meta.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"status-indicators": "Status indicators",
3+
"ace-sections": "ACE permissions"
4+
}

‎pages/scoreboard/guides/ace-sections.mdx

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import { Steps } from 'nextra/components'
2+
3+
# Control visible sections using ACE permissions
4+
5+
You can control the visibility of individual sections in the scoreboard using ACE permissions.
6+
This is useful if you want to show/hide certain sections only for certain players.
7+
8+
This guide will use the *groups* section as an example, but it works the same for all options.
9+
10+
11+
12+
## Requirements
13+
- understanding of FiveM ACE permissions
14+
- your own custom logic for controlling and setting the permissions
15+
16+
17+
18+
## Configuration
19+
To enable ACE permissions for a section, you need to change the value of it in the `config.lua` file.
20+
21+
**There are 3 valid values:**
22+
`true{:lua}`: Visible for everyone
23+
`false{:lua}`: Completely disabled and hidden for everyone
24+
`'limited'{:lua}`: Visible only for players with the required ACE permission
25+
26+
In this case, we want to use the last value → `'limited'{:lua}`.
27+
28+
29+
30+
## Steps
31+
32+
<Steps>
33+
34+
### Modify the config file
35+
Change the value of `groups` in `visibleSections` from `true{:lua}` to `'limited'{:lua}`.
36+
37+
```lua {2} /'limited'/
38+
visibleSections = {
39+
groups = 'limited',
40+
players = true,
41+
playerNames = true,
42+
playerIds = true,
43+
statusIndicators = true,
44+
footer = true,
45+
},
46+
```
47+
48+
### Restart the resource
49+
50+
### Set the ACE permission
51+
Use your own custom code and logic to set the ACE permission for specific players you want to see the group section. You can use [this](https://forum.cfx.re/t/90917) guide as a reference.
52+
53+
ACE permission for the group section is `scoreboard.show.groups`.
54+
For other options, just replace `groups` with the name of the option (e.g. `scoreboard.show.playerNames`).
55+
56+
You can set the ACE permission using `ExecuteCommand` in your server-side code
57+
```lua filename="server.lua"
58+
ExecuteCommand('add_ace group.admin scoreboard.show.groups allow')
59+
```
60+
61+
or anywhere in your `server.cfg` file.
62+
```bash filename="server.cfg"
63+
add_ace group.admin scoreboard.show.groups allow
64+
```
65+
66+
You can add or remove the permissions during runtime. It will take effect immediately after reopening the scoreboard.
67+
68+
### Test it
69+
If you did everything correctly, the group section will be visible only for players with the `scoreboard.show.groups` ACE permission. In this example, we set it to the `group.admin` group.
70+
71+
**In case it's not working, read this whole page again from the beginning and check if you missed something.**
72+
73+
</Steps>

‎pages/scoreboard/guides/status-indicators.mdx

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import { Steps } from 'nextra/components'
2+
3+
# Change states of status indicators
4+
5+
You can change the states of individual status indicators.
6+
This is useful if you want to indicate certain YES or NO states for players.
7+
8+
This guide will show you how to change the state of `house_robbery` status indicator, but it works the same for all indicators.
9+
10+
11+
12+
## Requirements
13+
- ability to write your own custom logic for controlling the states
14+
15+
16+
17+
## Configuration
18+
You need to find the status indicator ID. This can be found in the `config.lua` file.
19+
Each status indicator needs to have a unique ID so you can identify it.
20+
21+
```lua filename="config.lua" {2} /'house_robbery'/
22+
statusIndicators = {
23+
{ id = 'house_robbery', label = 'House robbery', icon = 'mdi:house', defaultState = true },
24+
{ id = 'store_robbery', label = 'Store robbery', icon = 'mdi:store', defaultState = false },
25+
{ id = 'bank_robbery', label = 'Bank robbery', icon = 'mdi:bank' },
26+
},
27+
```
28+
29+
30+
31+
## Steps
32+
33+
<Steps>
34+
35+
### Create a custom server resource
36+
The state can be only changed from server-side resources.
37+
Create a new resource (or use an existing one) and add the following custom logic to it's server-side file.
38+
39+
### Use the `setIndicatorState` export
40+
```lua filename="server.lua" /'house_robbery'/ /true/
41+
exports.ac_scoreboard:setIndicatorState('house_robbery', true)
42+
```
43+
44+
The first argument is the indicator ID from `config.lua`.
45+
The second argument is a boolean value that sets the corresponding state.
46+
47+
You can also use non-networked `ac_scoreboard:setIndicatorState` server event, which works the same way.
48+
```lua filename="server.lua" /'house_robbery'/ /true/
49+
TriggerEvent('ac_scoreboard:setIndicatorState', 'house_robbery', true)
50+
```
51+
52+
### Test it
53+
Run your custom logic and see how the indicator state changes.
54+
All indicator changes take effect immediately after reopening the scoreboard.
55+
56+
**In case it's not working, read this whole page again from the beginning and check if you missed something.**
57+
58+
</Steps>

‎pages/scoreboard/index.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Getting started
2+
3+
**AC Scoreboard** is the ultimate standalone scoreboard solution for your server.
4+
5+
You can use any supported framework to enable additional features such as group list.
6+
Supported frameworks are [ox_core](https://github.com/overextended/ox_core), [qbx_core](https://github.com/Qbox-project/qbx_core), [qb-core](https://github.com/qbcore-framework/qb-core) and [es_extended](https://github.com/esx-framework/esx_core).
7+
8+
### Features
9+
- Customizable title (server name and logo)
10+
- Group list with each group's player count
11+
- Player list with their server ID
12+
- Status indicators that can be used for anything (e.g. if players can rob stores)
13+
- Select on which side of the screen is the scoreboard
14+
- Customizable UI settings (background blur, close behavior)
15+
- Choose what parts should be visible
16+
- Total player count and copyable server ID
17+
18+
### Preview
19+
<iframe width="560" height="315" src="https://www.youtube.com/embed/D_S4OmYOKJA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

0 commit comments

Comments
 (0)