Skip to content

Commit 286b68b

Browse files
JaylyDevJaylyDev
authored
Fix & Update OfflinePlayer (#343)
* update offline-player * Add version
1 parent df6e5c1 commit 286b68b

File tree

4 files changed

+371
-182
lines changed

4 files changed

+371
-182
lines changed

‎scripts/offline-player/README.md

Lines changed: 26 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,173 +1,48 @@
1-
# Offline Player
1+
# Offline Player v0.2.0
22

33
Represents a reference to a player identity and the data belonging to a player that is stored on the disk and can, thus, be retrieved without the player needing to be online.
44

5-
## Summary
6-
7-
Using either `index.js` or `index.ts` file:
8-
95
```js
10-
import { OfflinePlayer } from "offline-player/index";
6+
import { OfflinePlayer } from "offline-player/index.js";
117

128
// Get data via player.id (Recommended)
139
const player = OfflinePlayer.get('-68719476735');
1410
// Or get via player.name
1511
const player = OfflinePlayer.get('JaylyPlays');
1612
```
1713

18-
## Properties
19-
- [level](#level)
20-
- [name](#name)
21-
- [totalXpNeededForNextLevel](#totalxpneededfornextlevel)
22-
- [xpEarnedAtCurrentLevel](#xpearnedatcurrentlevel)
23-
- [gameMode](#gamemode)
24-
- [lastPlayed](#lastplayed)
25-
26-
### **level**
27-
`readonly level: number;`
28-
29-
The current overall level for the player, based on their experience.
30-
31-
Type: *number*
32-
33-
### **name**
34-
`readonly name: string;`
35-
36-
Name of the player.
37-
38-
Type: *string*
39-
40-
### **totalXpNeededForNextLevel**
41-
`readonly totalXpNeededForNextLevel: number;`
42-
43-
The overall total set of experience needed to achieve the next level for a player.
44-
45-
Type: *number*
46-
47-
### **xpEarnedAtCurrentLevel**
48-
`readonly xpEarnedAtCurrentLevel: number;`
49-
50-
The current set of experience achieved for the player.
51-
52-
Type: *number*
53-
54-
### **gameMode**
55-
`readonly gameMode: GameMode;`
56-
57-
The current gamemode for the player.
58-
59-
Type: *GameMode*
60-
61-
### **lastPlayed**
62-
`readonly lastPlayed: number;`
63-
64-
Gets the last date and time that this player was witnessed on this server. It will return Date of last log-in for this player in the amount of milliseconds since midnight, January 1, 1970 UTC.
65-
66-
Type: *number*
67-
68-
## Methods
69-
- [get](#get)
70-
- [get](#get-1)
71-
- [getSpawnPoint](#getspawnpoint)
72-
- [getTotalXp](#gettotalxp)
73-
- [isOp](#isop)
74-
- [getPlayer](#getplayer)
75-
76-
### **get**
77-
`
78-
static get(id: string): OfflinePlayer;
79-
`
80-
81-
Gets the player by the given ID, regardless if they are offline or online. This will return an object even if the player does not exist. To this method, all players will exist.
82-
83-
#### **Parameters**
84-
- **id**: *string*
85-
86-
the ID of the player to retrieve.
87-
88-
#### **Returns** *OfflinePlayer*
89-
90-
### **get**
91-
92-
`
93-
static get(name: string): OfflinePlayer;
94-
`
95-
96-
Gets the player by the given name, regardless if they are offline or online. This will return an object even if the player does not exist. To this method, all players will exist.
97-
98-
> [!CAUTION]
99-
> Persistent storage of users should be by ID as names are no longer unique past a single session.
100-
101-
#### **Parameters**
102-
- **name**: *string*
103-
104-
the name of the player to retrieve.
105-
106-
#### **Returns** *OfflinePlayer*
107-
108-
### **getSpawnPoint**
109-
`
110-
getSpawnPoint(): DimensionLocation | undefined
111-
`
112-
113-
Gets the current spawn point of the player.
114-
115-
#### **Returns** *DimensionLocation* | *undefined*
116-
117-
### **getTotalXp**
118-
`
119-
getTotalXp(): number
120-
`
121-
122-
Gets the total experience of the Player.
123-
124-
#### **Returns** *number*
125-
126-
### **isOp**
127-
`
128-
isOp(): boolean
129-
`
130-
131-
Returns true if this player has operator-level permissions.
14+
## Summary
13215

133-
#### **Returns** *boolean*
16+
Using either `index.js` with `index.d.ts` file, or `index.ts` file if you're working with TypeScript.
13417

135-
> [!IMPORTANT]
136-
> This function can only be used within Beta APIs.
18+
### Basic Player Data
13719

138-
### **getPlayer**
139-
`
140-
getPlayer(): Player | undefined
141-
`
20+
Following data are saved into dynamic properties:
14221

143-
If the player is online, this will return that player corresponds to.
22+
- `dimension: Dimension;`
23+
- `id: string;`
24+
- `isSneaking: boolean;`
25+
- `location: Vector3;`
26+
- `typeId = "minecraft:player";`
27+
- `level: number;`
28+
- `name: string;`
29+
- `totalXpNeededForNextLevel: number;`
30+
- `xpEarnedAtCurrentLevel: number;`
31+
- `gameMode: GameMode;`
32+
- `lastPlayed: number;`
33+
- `scoreboardIdentity?: ScoreboardOfflineIdentity;`
34+
- `getSpawnPoint(): DimensionLocation | undefined;`
35+
- `getTotalXp(): number;`
36+
- `isOp(): boolean;`
37+
- `getPlayer(): Player | undefined;` Gets the player object if the player is online.
14438

145-
#### **Returns** *Player | undefined*
39+
### Getting Player Scores from Scoreboard
14640

147-
## Schema
41+
If `offlinePlayer.scoreboardIdentity` exists, it means player's scoreboard data can be accessed offline.
14842

43+
Example:
14944
```ts
150-
import { Dimension, DimensionLocation, GameMode, Player, Vector3 } from "@minecraft/server";
151-
export class OfflinePlayer {
152-
private constructor();
153-
static get(id: `${number}`): OfflinePlayer;
154-
static get(name: string): OfflinePlayer;
155-
readonly dimension: Dimension;
156-
readonly id: string;
157-
readonly isSneaking: boolean;
158-
readonly location: Vector3;
159-
readonly typeId = "minecraft:player";
160-
readonly level: number;
161-
readonly name: string;
162-
readonly totalXpNeededForNextLevel: number;
163-
readonly xpEarnedAtCurrentLevel: number;
164-
readonly gameMode: GameMode;
165-
readonly lastPlayed: number;
166-
getSpawnPoint(): DimensionLocation | undefined;
167-
getTotalXp(): number;
168-
isOp(): boolean;
169-
getPlayer(): Player | undefined;
170-
}
45+
offlinePlayer.scoreboardIdentity.getScore('objective');
17146
```
17247

17348
## License

‎scripts/offline-player/index.d.ts

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
import { Dimension, DimensionLocation, GameMode, Player, ScoreboardIdentityType, Vector3 } from "@minecraft/server";
2+
/**
3+
* @beta
4+
* Contains an identity of the scoreboard item.
5+
*/
6+
declare class ScoreboardOfflineIdentity {
7+
private constructor();
8+
/**
9+
* @remarks
10+
* Returns the player-visible name of this identity.
11+
*
12+
*/
13+
readonly displayName: string;
14+
/**
15+
* @remarks
16+
* Identifier of the scoreboard identity.
17+
*
18+
*/
19+
readonly id: number;
20+
/**
21+
* @remarks
22+
* Type of the scoreboard identity.
23+
*
24+
*/
25+
readonly type = ScoreboardIdentityType.Player;
26+
/**
27+
* @remarks
28+
* Gets the current score for this participant based on an
29+
* objective.
30+
*
31+
* @param objective
32+
* The objective to retrieve the score for.
33+
* @returns
34+
* Score value.
35+
* @throws This function can throw errors.
36+
*/
37+
getScore(objectiveId: string): number | undefined;
38+
}
39+
/**
40+
* @description
41+
* Represents a reference to a player identity and the data
42+
* belonging to a player that is stored on the disk and can,
43+
* thus, be retrieved without the player needing to be online.
44+
*/
45+
declare class OfflinePlayer {
46+
private constructor();
47+
/**
48+
* @description
49+
* Gets the player by the given ID, regardless if they are offline or online.
50+
* This will return an object even if the player does not exist. To this method, all players will exist.
51+
* @param id the ID of the player to retrieve
52+
* @returns an offline player.
53+
*/
54+
static get(id: `${number}`): OfflinePlayer;
55+
/**
56+
* @deprecated
57+
* Persistent storage of users should be by ID as names are no longer unique past a single session.
58+
* @description
59+
* Gets the player by the given name, regardless if they are offline or online.
60+
* This will return an object even if the player does not exist. To this method, all players will exist.
61+
* @param name the name the player to retrieve
62+
* @returns an offline player.
63+
*/
64+
static get(name: string): OfflinePlayer;
65+
/**
66+
* @remarks
67+
* Dimension that the entity is currently within.
68+
*
69+
*/
70+
readonly dimension: Dimension;
71+
/**
72+
* @remarks
73+
* Unique identifier of the entity. This identifier is intended
74+
* to be consistent across loads of a world instance. No
75+
* meaning should be inferred from the value and structure of
76+
* this unique identifier - do not parse or interpret it. This
77+
* property is accessible even if {@link Entity.isValid} is
78+
* false.
79+
*
80+
*/
81+
readonly id: string;
82+
/**
83+
* @remarks
84+
* Whether the entity is sneaking - that is, moving more slowly
85+
* and more quietly.
86+
*
87+
*/
88+
readonly isSneaking: boolean;
89+
/**
90+
* @remarks
91+
* Current location of the entity.
92+
*
93+
*/
94+
readonly location: Vector3;
95+
/**
96+
* @remarks
97+
* Identifier of the type of the entity - for example,
98+
* 'minecraft:skeleton'. This property is accessible even if
99+
* {@link Entity.isValid} is false.
100+
*
101+
*/
102+
readonly typeId = "minecraft:player";
103+
/**
104+
* @remarks
105+
* The current overall level for the player, based on their
106+
* experience.
107+
*
108+
*/
109+
readonly level: number;
110+
/**
111+
* @remarks
112+
* Name of the player.
113+
*
114+
*/
115+
readonly name: string;
116+
/**
117+
* @remarks
118+
* The overall total set of experience needed to achieve the
119+
* next level for a player.
120+
*
121+
*/
122+
readonly totalXpNeededForNextLevel: number;
123+
/**
124+
* @remarks
125+
* The current set of experience achieved for the player.
126+
*
127+
*/
128+
readonly xpEarnedAtCurrentLevel: number;
129+
/**
130+
* @remarks
131+
* The current gamemode for the player.
132+
*
133+
*/
134+
readonly gameMode: GameMode;
135+
/**
136+
* @remarks
137+
* Gets the last date and time that this player was witnessed
138+
* on this server.
139+
* It will return Date of last log-in for this player in the
140+
* amount of milliseconds since midnight, January 1, 1970 UTC.
141+
*
142+
*/
143+
readonly lastPlayed: number;
144+
/**
145+
* @remarks
146+
* Returns a scoreboard identity that represents this entity.
147+
* Will remain valid when the entity is killed.
148+
*
149+
*/
150+
readonly scoreboardIdentity?: ScoreboardOfflineIdentity;
151+
/**
152+
* @remarks
153+
* Gets the current spawn point of the player.
154+
*
155+
*/
156+
getSpawnPoint(): DimensionLocation | undefined;
157+
/**
158+
* @remarks
159+
* Gets the total experience of the Player.
160+
*
161+
*/
162+
getTotalXp(): number;
163+
/**
164+
* @beta
165+
* @remarks
166+
* Returns true if this player has operator-level permissions.
167+
*
168+
*/
169+
isOp(): boolean;
170+
/**
171+
* @remarks
172+
* If the player is online, this will return that player corresponds to.
173+
*
174+
*/
175+
getPlayer(): Player | undefined;
176+
}
177+
export { OfflinePlayer, ScoreboardOfflineIdentity };

0 commit comments

Comments
 (0)