feat(scoreboard): v2 docs (#5)

index.css

@@ -8,3 +8,9 @@
   display: flex;
   margin-top: 0.5rem;
 }
+
+.ac-splitter {
+  margin-top: 2rem;
+  margin-bottom: 2rem;
+  border-top-width: 3px;
+}

pages/_meta.json

@@ -1,11 +1,12 @@
 {
   "index": "Home",
-  "radio": "ac_radio",
-  "documents": "ac_documents",
-  "gifts": "ac_gifts",
+  "radio": "AC Radio",
+  "scoreboard": "AC Scoreboard",
+  "documents": "AC Documents",
+  "gifts": "AC Gifts",
   "link_tebex": {
     "title": "Tebex",
-    "href": "https://ac-scripts.tebex.io/",
+    "href": "https://store.acscripts.dev/",
     "type": "page",
     "newWindow": true
   },

pages/scoreboard/_meta.json

@@ -0,0 +1,6 @@
+{
+  "index": "Introduction",
+  "config": "Configuration",
+  "guides": "Guides",
+  "issues": "Common issues"
+}

pages/scoreboard/config.mdx

@@ -0,0 +1,201 @@
+# Configuration
+
+
+## settings \{ \}
+
+### title
+Text and logo shown in the scoreboard header.
+
+**Accepted values**  
+text: `string`  
+logo: `string` (URL to the image file)
+
+---
+
+### side
+On which side of the screen should the scoreboard be displayed.
+
+**Accepted values**  
+`string` → `'left'{:lua}` or `'right'{:lua}`
+
+---
+
+### showOverlay
+Enable showing background overlay when scoreboard is open.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### closeOnEscape
+Close scoreboard when the escape key is pressed.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### closeOnOutsideClick
+Close scoreboard when clicked outside of it.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### uppercaseNames
+Make all player names uppercase.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### highlightEmptyGroups
+Highlight empty groups by making the count number red.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### compactPlayers
+Change the player row height to be more compact.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### compactGroups
+Change the group row height to be more compact.
+
+**Accepted values**  
+`boolean` (true / false)
+
+---
+
+### playerColumns
+How many columns to use for player list.  
+`2` columns will show 2 players per row, so it will be more compact.
+
+**Accepted values**  
+`number` → `1{:lua}` or `2{:lua}`
+
+---
+
+### groupColumns
+How many columns to use for group list.  
+`2` columns will show 2 groups per row, so it will be more compact.
+
+**Accepted values**  
+`number` → `1{:lua}` or `2{:lua}`
+
+
+
+<hr className="ac-splitter" />
+
+
+
+## visibleSections \{ \}
+The following accepted values are valid for all options in this category.  
+See the [guide](./guides/ace-sections) for more information on how to use ACE permissions.
+
+**Accepted values**  
+`true{:lua}`: Visible for everyone  
+`false{:lua}`: Completely disabled and hidden for everyone  
+`'limited'{:lua}`: Visible only for players with the required ACE permission
+
+### groups
+Show or hide the groups section.
+
+---
+
+### players
+Show or hide the players section.
+
+---
+
+### playerNames
+Show or hide player names in the players section.  
+Setting this to `false{:lua}` will change all player names to "**Anonymous player**".
+
+---
+
+### playerIds
+Show or hide player IDs in the players section.  
+Setting this to `false{:lua}` will hide all player IDs.
+
+---
+
+### statusIndicators
+Show or hide the status indicators section.
+
+---
+
+### footer
+Show or hide the footer section.
+
+
+
+<hr className="ac-splitter" />
+
+
+
+## commandName
+Name of the command to open the scoreboard.
+
+**Accepted values**  
+`string`
+
+
+
+## commandKey
+Default keybind for the radio command.
+
+**Accepted values**  
+`false{:lua}` = Keybind will not be created at all.  
+`''{:lua}` = Empty quotes for creating the keybind, but not setting a default key.  
+`'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.
+
+
+
+## includeOffDuty
+Include off-duty players in the group count.
+
+**Accepted values**  
+`boolean` (true / false)
+
+
+
+## groups
+Individual group rows shown in scoreboard.
+
+**Accepted values**  
+`table[]` with the following structure:
+
+```ts
+{
+  label: string; // Name of the group row shown in scoreboard
+  groups: string[]; // Array of groups to include in this row's total count
+}
+```
+
+
+
+## statusIndicators
+Individual status indicators shown in the section.  
+For more information on how to use custom icons, see the guide [here](./issues#status-indicator-icon-is-not-showing).  
+To learn how to change the state of these indicators, see the guide [here](./guides/status-indicators).
+
+**Accepted values**  
+`table[]` with the following structure:
+
+```ts
+{
+  id: string; // Unique identifier for the status indicator, used in your exports to change the state
+  label: string; // Label visible in the hover tooltip
+  icon: string; // Icon of the indicator, must be a valid Iconify name
+  defaultState?: boolean; // Default state of the indicator; true = on, false = off
+}

pages/scoreboard/guides/_meta.json

@@ -0,0 +1,4 @@
+{
+  "status-indicators": "Status indicators",
+  "ace-sections": "ACE permissions"
+}

pages/scoreboard/guides/ace-sections.mdx

@@ -0,0 +1,73 @@
+import { Steps } from 'nextra/components'
+
+# Control visible sections using ACE permissions
+
+You can control the visibility of individual sections in the scoreboard using ACE permissions.  
+This is useful if you want to show/hide certain sections only for certain players.
+
+This guide will use the *groups* section as an example, but it works the same for all options.
+
+
+
+## Requirements
+- understanding of FiveM ACE permissions  
+- your own custom logic for controlling and setting the permissions
+
+
+
+## Configuration
+To enable ACE permissions for a section, you need to change the value of it in the `config.lua` file.
+
+**There are 3 valid values:**  
+`true{:lua}`: Visible for everyone  
+`false{:lua}`: Completely disabled and hidden for everyone  
+`'limited'{:lua}`: Visible only for players with the required ACE permission
+
+In this case, we want to use the last value → `'limited'{:lua}`.
+
+
+
+## Steps
+
+<Steps>
+
+### Modify the config file
+Change the value of `groups` in `visibleSections` from `true{:lua}` to `'limited'{:lua}`.
+
+```lua {2} /'limited'/
+visibleSections = {
+    groups = 'limited',
+    players = true,
+    playerNames = true,
+    playerIds = true,
+    statusIndicators = true,
+    footer = true,
+},
+```
+
+### Restart the resource
+
+### Set the ACE permission
+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.
+
+ACE permission for the group section is `scoreboard.show.groups`.  
+For other options, just replace `groups` with the name of the option (e.g. `scoreboard.show.playerNames`).
+
+You can set the ACE permission using `ExecuteCommand` in your server-side code
+```lua filename="server.lua"
+ExecuteCommand('add_ace group.admin scoreboard.show.groups allow')
+```
+
+or anywhere in your `server.cfg` file.
+```bash filename="server.cfg"
+add_ace group.admin scoreboard.show.groups allow
+```
+
+You can add or remove the permissions during runtime. It will take effect immediately after reopening the scoreboard.
+
+### Test it
+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.
+
+**In case it's not working, read this whole page again from the beginning and check if you missed something.**
+
+</Steps>

pages/scoreboard/guides/status-indicators.mdx

@@ -0,0 +1,58 @@
+import { Steps } from 'nextra/components'
+
+# Change states of status indicators
+
+You can change the states of individual status indicators.  
+This is useful if you want to indicate certain YES or NO states for players.
+
+This guide will show you how to change the state of `house_robbery` status indicator, but it works the same for all indicators.
+
+
+
+## Requirements
+- ability to write your own custom logic for controlling the states
+
+
+
+## Configuration
+You need to find the status indicator ID. This can be found in the `config.lua` file.  
+Each status indicator needs to have a unique ID so you can identify it.
+
+```lua filename="config.lua" {2} /'house_robbery'/
+statusIndicators = {
+    { id = 'house_robbery', label = 'House robbery', icon = 'mdi:house', defaultState = true },
+    { id = 'store_robbery', label = 'Store robbery', icon = 'mdi:store', defaultState = false },
+    { id = 'bank_robbery', label = 'Bank robbery', icon = 'mdi:bank' },
+},
+```
+
+
+
+## Steps
+
+<Steps>
+
+### Create a custom server resource
+The state can be only changed from server-side resources.  
+Create a new resource (or use an existing one) and add the following custom logic to it's server-side file.
+
+### Use the `setIndicatorState` export
+```lua filename="server.lua" /'house_robbery'/ /true/
+exports.ac_scoreboard:setIndicatorState('house_robbery', true)
+```
+
+The first argument is the indicator ID from `config.lua`.  
+The second argument is a boolean value that sets the corresponding state.
+
+You can also use non-networked `ac_scoreboard:setIndicatorState` server event, which works the same way.  
+```lua filename="server.lua" /'house_robbery'/ /true/
+TriggerEvent('ac_scoreboard:setIndicatorState', 'house_robbery', true)
+```
+
+### Test it
+Run your custom logic and see how the indicator state changes.  
+All indicator changes take effect immediately after reopening the scoreboard.
+
+**In case it's not working, read this whole page again from the beginning and check if you missed something.**
+
+</Steps>

pages/scoreboard/index.md

@@ -0,0 +1,19 @@
+# Getting started
+
+**AC Scoreboard** is the ultimate standalone scoreboard solution for your server.
+
+You can use any supported framework to enable additional features such as group list.  
+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).
+
+### Features
+- Customizable title (server name and logo)
+- Group list with each group's player count
+- Player list with their server ID
+- Status indicators that can be used for anything (e.g. if players can rob stores)
+- Select on which side of the screen is the scoreboard
+- Customizable UI settings (background blur, close behavior)
+- Choose what parts should be visible
+- Total player count and copyable server ID
+
+### Preview
+<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>