Skip to content

Commit e7fb7c3

Browse files
D4isDAVIDD4isDAVID
committed
Sort out documentation
1 parent a47e56a commit e7fb7c3

6 files changed

Lines changed: 279 additions & 160 deletions

File tree

‎docs/README.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# Documentation
22

3-
This documentation for d4_playerdata covers usage, concepts, the API, and
4-
internal design details.
3+
This documentation covers usage, concepts, the API, and internal design details.
54

65
## Getting Started
76

@@ -14,8 +13,8 @@ Essential information for anyone using the resource.
1413

1514
Reference for developers integrating the resource into their resources.
1615

17-
- **[Events](./api/events.md)**
18-
- **[Exports](./api/exports.md)**
16+
- **[Users API](./api/users.md):** Exports and events to manage User IDs
17+
- **[Data API](./api/data.md):** Exports and events to manage Data IDs
1918

2019
## Internals
2120

docs/api/exports.md renamed to docs/api/data.md

Lines changed: 30 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,6 @@
1-
# Exports
1+
# Data API
22

3-
## Server
4-
5-
### Get User ID From Player
6-
7-
```
8-
exports.d4_playerdata:getUserId(player)
9-
```
10-
11-
Returns the given player's User ID.
12-
13-
#### Parameters
14-
15-
- `player: string | integer` - The player Net ID.
16-
17-
#### Returns
18-
19-
- `integer?` - The player's User ID.
20-
21-
### Resolve User ID From Identifiers
22-
23-
```
24-
exports.d4_playerdata:resolveUserId(identifiers)
25-
```
26-
27-
Resolves and returns a User ID based on the given identifiers.
28-
29-
#### Parameters
30-
31-
- `identifiers: string[]` - The player identifiers.
32-
33-
#### Returns
34-
35-
- `integer?` - The resolved User ID.
36-
37-
### Is User ID Connected
38-
39-
```
40-
exports.d4_playerdata:isUserIdConnected(userId)
41-
```
42-
43-
Returns whether the given User ID is connected to the server.
44-
45-
#### Parameters
46-
47-
- `userId: integer` - The User ID.
48-
49-
#### Returns
50-
51-
- `boolean` - Whether the given User ID is connected.
52-
53-
### Get Players From User ID
54-
55-
```
56-
exports.d4_playerdata:getPlayersFromUserId(userId)
57-
```
58-
59-
Returns the player Net IDs linked to the given User ID.
60-
The returned table will be empty when offline.
61-
62-
#### Parameters
63-
64-
- `userId: integer` - The player's User ID.
65-
66-
#### Returns
67-
68-
- `string[]` - The player Net IDs linked to the given User ID.
69-
70-
### Get User ID From Identifier
71-
72-
```
73-
exports.d4_playerdata:getUserIdFromIdentifier(identifier)
74-
```
75-
76-
Returns the User ID linked to the given identifier.
77-
78-
#### Parameters
79-
80-
- `identifier: string` - The identifier.
81-
82-
#### Returns
83-
84-
- `integer?` - The User ID linked to the given identifier.
85-
86-
### Get Identifiers From User ID
87-
88-
```
89-
exports.d4_playerdata:getIdentifiersFromUserId(userId)
90-
```
91-
92-
Returns the identifiers linked to the given User ID.
93-
94-
#### Parameters
95-
96-
- `userId: integer` - The User ID.
97-
98-
#### Returns
99-
100-
- `string[]` - The identifiers linked to the given User ID.
3+
## Server Exports
1014

1025
### Get Data ID Assigned to Player
1036

@@ -244,3 +147,31 @@ Returns whether the given Data IDs is linked to the given User ID.
244147
#### Returns
245148

246149
- `boolean` - Whether the given Data ID is linked to the given User ID.
150+
151+
## Server Events
152+
153+
### Data Assigned
154+
155+
```
156+
AddEventHandler('d4_playerdata:dataAssigned', function(source, dataId) end)
157+
```
158+
159+
Triggered after a player is assigned a Data ID.
160+
161+
#### Parameters
162+
163+
- `source: string` - The player Net ID.
164+
- `dataId: integer` - The assigned Data ID.
165+
166+
### Data Unassigned
167+
168+
```
169+
AddEventHandler('d4_playerdata:dataUnassigned', function(source, dataId) end)
170+
```
171+
172+
Triggered after a player is unassigned a Data ID.
173+
174+
#### Parameters
175+
176+
- `source: string` - The player Net ID.
177+
- `dataId: integer` - The unassigned Data ID.

‎docs/api/events.md‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎docs/api/users.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Users API
2+
3+
## Server Exports
4+
5+
### Get User ID From Player
6+
7+
```
8+
exports.d4_playerdata:getUserId(player)
9+
```
10+
11+
Returns the given player's User ID.
12+
13+
#### Parameters
14+
15+
- `player: string | integer` - The player Net ID.
16+
17+
#### Returns
18+
19+
- `integer?` - The player's User ID.
20+
21+
### Resolve User ID From Identifiers
22+
23+
```
24+
exports.d4_playerdata:resolveUserId(identifiers)
25+
```
26+
27+
Resolves and returns a User ID based on the given identifiers.
28+
29+
#### Parameters
30+
31+
- `identifiers: string[]` - The player identifiers.
32+
33+
#### Returns
34+
35+
- `integer?` - The resolved User ID.
36+
37+
### Is User ID Connected
38+
39+
```
40+
exports.d4_playerdata:isUserIdConnected(userId)
41+
```
42+
43+
Returns whether the given User ID is connected to the server.
44+
45+
#### Parameters
46+
47+
- `userId: integer` - The User ID.
48+
49+
#### Returns
50+
51+
- `boolean` - Whether the given User ID is connected.
52+
53+
### Get Players From User ID
54+
55+
```
56+
exports.d4_playerdata:getPlayersFromUserId(userId)
57+
```
58+
59+
Returns the player Net IDs linked to the given User ID.
60+
The returned table will be empty when offline.
61+
62+
#### Parameters
63+
64+
- `userId: integer` - The player's User ID.
65+
66+
#### Returns
67+
68+
- `string[]` - The player Net IDs linked to the given User ID.
69+
70+
### Get User ID From Identifier
71+
72+
```
73+
exports.d4_playerdata:getUserIdFromIdentifier(identifier)
74+
```
75+
76+
Returns the User ID linked to the given identifier.
77+
78+
#### Parameters
79+
80+
- `identifier: string` - The identifier.
81+
82+
#### Returns
83+
84+
- `integer?` - The User ID linked to the given identifier.
85+
86+
### Get Identifiers From User ID
87+
88+
```
89+
exports.d4_playerdata:getIdentifiersFromUserId(userId)
90+
```
91+
92+
Returns the identifiers linked to the given User ID.
93+
94+
#### Parameters
95+
96+
- `userId: integer` - The User ID.
97+
98+
#### Returns
99+
100+
- `string[]` - The identifiers linked to the given User ID.
101+
102+
## Server Events
103+
104+
### User Joined
105+
106+
```
107+
AddEventHandler('d4_playerdata:userJoined', function(source, userId) end)
108+
```
109+
110+
Triggered after a player is assigned a User ID.
111+
112+
#### Parameters
113+
114+
- `source: string` - The player Net ID.
115+
- `userId: integer` - The assigned User ID.
116+
117+
### User Left
118+
119+
```
120+
AddEventHandler('d4_playerdata:userLeft', function(source, userId) end)
121+
```
122+
123+
Triggered after a player is unassigned a User ID.
124+
125+
#### Parameters
126+
127+
- `source: string` - The player Net ID.
128+
- `userId: integer` - The assigned User ID.
129+

‎docs/player-data.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,52 @@
11
# Player Data
22

3-
TODO
3+
> TL;DR
4+
> This resource assigns players a persistent User ID linked to player
5+
> identifiers, and provides Data IDs for data similar to characters or save
6+
> files. Use User IDs for identity, and Data IDs for gameplay state.
7+
8+
The main functionality of this resource is identifying players and assigning
9+
them persistent User and Data IDs. This document explains the purpose and
10+
behavior of these IDs.
11+
12+
Please read the following links for more context:
13+
- [Identifier Types](https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/GetPlayerIdentifiers/#identifier-types)
14+
15+
## User IDs
16+
17+
To save player data across logins and restarts, FiveM provides us with player
18+
identifiers. Most frameworks use a single identifier; typically `license2` or
19+
`license`, based on availability. This can pose a problem, however, as
20+
`license2` is not always available, and `license` is prone to changes. This can
21+
lead to some players losing access to their data, or not being able to join at
22+
all. The other identifiers aren't reliable either, as they might require players
23+
to play using a specific platform, or link an external account, locking out
24+
certain players.
25+
26+
This resource solves this by using *all* available identifiers, except for `ip`,
27+
as it is not specific enough. These identifiers will be linked to a User ID. The
28+
User ID is an integer value assigned to players, intended for developers to use
29+
as a replacement for identifiers. This allows the resource to reliably identify
30+
the player, while your resources handle the rest.
31+
32+
When a player joins the server, this resource collects their identifiers. If a
33+
linked User ID is found, then it is assigned to the player. If new and unlinked
34+
identifiers are found, they are also linked to the User ID. In the case that
35+
multiple User IDs are found, the oldest User ID is assigned. Existing identifier
36+
links are not modified, preventing accidental reassignment. If no linked User ID
37+
is found, a new one is created and linked to the identifiers.
38+
39+
## Data IDs
40+
41+
The Data ID is an integer value provided by this resource, similar to a
42+
character or a save file. One User ID can have multiple Data IDs, similar to
43+
having multiple characters or save files. This is intended for developers to use
44+
as a framework-agnostic solution to save player data, replacing
45+
framework-dependent character IDs. It is recommended to almost always use Data
46+
IDs to save data. Use User IDs only for data that should persist across all Data
47+
IDs.
48+
49+
By default, when a player joins, this resource automatically assigns the first
50+
Data ID linked to the player's User ID, or creates one if none exist. Other
51+
resources can disable this functionality to implement their own Data ID
52+
assignments, such as a character selection screen.

0 commit comments

Comments
 (0)