Skip to content

Commit

Permalink
Fix & Update OfflinePlayer (#343)
Browse files Browse the repository at this point in the history
* update offline-player

* Add version
  • Loading branch information
JaylyDev authored Dec 26, 2023
1 parent df6e5c1 commit 286b68b
Show file tree
Hide file tree
Showing 4 changed files with 371 additions and 182 deletions.
177 changes: 26 additions & 151 deletions scripts/offline-player/README.md
Original file line number Diff line number Diff line change
@@ -1,173 +1,48 @@
# Offline Player
# Offline Player v0.2.0

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.

## Summary

Using either `index.js` or `index.ts` file:

```js
import { OfflinePlayer } from "offline-player/index";
import { OfflinePlayer } from "offline-player/index.js";

// Get data via player.id (Recommended)
const player = OfflinePlayer.get('-68719476735');
// Or get via player.name
const player = OfflinePlayer.get('JaylyPlays');
```

## Properties
- [level](#level)
- [name](#name)
- [totalXpNeededForNextLevel](#totalxpneededfornextlevel)
- [xpEarnedAtCurrentLevel](#xpearnedatcurrentlevel)
- [gameMode](#gamemode)
- [lastPlayed](#lastplayed)

### **level**
`readonly level: number;`

The current overall level for the player, based on their experience.

Type: *number*

### **name**
`readonly name: string;`

Name of the player.

Type: *string*

### **totalXpNeededForNextLevel**
`readonly totalXpNeededForNextLevel: number;`

The overall total set of experience needed to achieve the next level for a player.

Type: *number*

### **xpEarnedAtCurrentLevel**
`readonly xpEarnedAtCurrentLevel: number;`

The current set of experience achieved for the player.

Type: *number*

### **gameMode**
`readonly gameMode: GameMode;`

The current gamemode for the player.

Type: *GameMode*

### **lastPlayed**
`readonly lastPlayed: number;`

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.

Type: *number*

## Methods
- [get](#get)
- [get](#get-1)
- [getSpawnPoint](#getspawnpoint)
- [getTotalXp](#gettotalxp)
- [isOp](#isop)
- [getPlayer](#getplayer)

### **get**
`
static get(id: string): OfflinePlayer;
`

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.

#### **Parameters**
- **id**: *string*

the ID of the player to retrieve.

#### **Returns** *OfflinePlayer*

### **get**

`
static get(name: string): OfflinePlayer;
`

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.

> [!CAUTION]
> Persistent storage of users should be by ID as names are no longer unique past a single session.
#### **Parameters**
- **name**: *string*

the name of the player to retrieve.

#### **Returns** *OfflinePlayer*

### **getSpawnPoint**
`
getSpawnPoint(): DimensionLocation | undefined
`

Gets the current spawn point of the player.

#### **Returns** *DimensionLocation* | *undefined*

### **getTotalXp**
`
getTotalXp(): number
`

Gets the total experience of the Player.

#### **Returns** *number*

### **isOp**
`
isOp(): boolean
`

Returns true if this player has operator-level permissions.
## Summary

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

> [!IMPORTANT]
> This function can only be used within Beta APIs.
### Basic Player Data

### **getPlayer**
`
getPlayer(): Player | undefined
`
Following data are saved into dynamic properties:

If the player is online, this will return that player corresponds to.
- `dimension: Dimension;`
- `id: string;`
- `isSneaking: boolean;`
- `location: Vector3;`
- `typeId = "minecraft:player";`
- `level: number;`
- `name: string;`
- `totalXpNeededForNextLevel: number;`
- `xpEarnedAtCurrentLevel: number;`
- `gameMode: GameMode;`
- `lastPlayed: number;`
- `scoreboardIdentity?: ScoreboardOfflineIdentity;`
- `getSpawnPoint(): DimensionLocation | undefined;`
- `getTotalXp(): number;`
- `isOp(): boolean;`
- `getPlayer(): Player | undefined;` Gets the player object if the player is online.

#### **Returns** *Player | undefined*
### Getting Player Scores from Scoreboard

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

Example:
```ts
import { Dimension, DimensionLocation, GameMode, Player, Vector3 } from "@minecraft/server";
export class OfflinePlayer {
private constructor();
static get(id: `${number}`): OfflinePlayer;
static get(name: string): OfflinePlayer;
readonly dimension: Dimension;
readonly id: string;
readonly isSneaking: boolean;
readonly location: Vector3;
readonly typeId = "minecraft:player";
readonly level: number;
readonly name: string;
readonly totalXpNeededForNextLevel: number;
readonly xpEarnedAtCurrentLevel: number;
readonly gameMode: GameMode;
readonly lastPlayed: number;
getSpawnPoint(): DimensionLocation | undefined;
getTotalXp(): number;
isOp(): boolean;
getPlayer(): Player | undefined;
}
offlinePlayer.scoreboardIdentity.getScore('objective');
```

## License
Expand Down
177 changes: 177 additions & 0 deletions scripts/offline-player/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
import { Dimension, DimensionLocation, GameMode, Player, ScoreboardIdentityType, Vector3 } from "@minecraft/server";
/**
* @beta
* Contains an identity of the scoreboard item.
*/
declare class ScoreboardOfflineIdentity {
private constructor();
/**
* @remarks
* Returns the player-visible name of this identity.
*
*/
readonly displayName: string;
/**
* @remarks
* Identifier of the scoreboard identity.
*
*/
readonly id: number;
/**
* @remarks
* Type of the scoreboard identity.
*
*/
readonly type = ScoreboardIdentityType.Player;
/**
* @remarks
* Gets the current score for this participant based on an
* objective.
*
* @param objective
* The objective to retrieve the score for.
* @returns
* Score value.
* @throws This function can throw errors.
*/
getScore(objectiveId: string): number | undefined;
}
/**
* @description
* 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.
*/
declare class OfflinePlayer {
private constructor();
/**
* @description
* 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.
* @param id the ID of the player to retrieve
* @returns an offline player.
*/
static get(id: `${number}`): OfflinePlayer;
/**
* @deprecated
* Persistent storage of users should be by ID as names are no longer unique past a single session.
* @description
* 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.
* @param name the name the player to retrieve
* @returns an offline player.
*/
static get(name: string): OfflinePlayer;
/**
* @remarks
* Dimension that the entity is currently within.
*
*/
readonly dimension: Dimension;
/**
* @remarks
* Unique identifier of the entity. This identifier is intended
* to be consistent across loads of a world instance. No
* meaning should be inferred from the value and structure of
* this unique identifier - do not parse or interpret it. This
* property is accessible even if {@link Entity.isValid} is
* false.
*
*/
readonly id: string;
/**
* @remarks
* Whether the entity is sneaking - that is, moving more slowly
* and more quietly.
*
*/
readonly isSneaking: boolean;
/**
* @remarks
* Current location of the entity.
*
*/
readonly location: Vector3;
/**
* @remarks
* Identifier of the type of the entity - for example,
* 'minecraft:skeleton'. This property is accessible even if
* {@link Entity.isValid} is false.
*
*/
readonly typeId = "minecraft:player";
/**
* @remarks
* The current overall level for the player, based on their
* experience.
*
*/
readonly level: number;
/**
* @remarks
* Name of the player.
*
*/
readonly name: string;
/**
* @remarks
* The overall total set of experience needed to achieve the
* next level for a player.
*
*/
readonly totalXpNeededForNextLevel: number;
/**
* @remarks
* The current set of experience achieved for the player.
*
*/
readonly xpEarnedAtCurrentLevel: number;
/**
* @remarks
* The current gamemode for the player.
*
*/
readonly gameMode: GameMode;
/**
* @remarks
* 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.
*
*/
readonly lastPlayed: number;
/**
* @remarks
* Returns a scoreboard identity that represents this entity.
* Will remain valid when the entity is killed.
*
*/
readonly scoreboardIdentity?: ScoreboardOfflineIdentity;
/**
* @remarks
* Gets the current spawn point of the player.
*
*/
getSpawnPoint(): DimensionLocation | undefined;
/**
* @remarks
* Gets the total experience of the Player.
*
*/
getTotalXp(): number;
/**
* @beta
* @remarks
* Returns true if this player has operator-level permissions.
*
*/
isOp(): boolean;
/**
* @remarks
* If the player is online, this will return that player corresponds to.
*
*/
getPlayer(): Player | undefined;
}
export { OfflinePlayer, ScoreboardOfflineIdentity };
Loading

0 comments on commit 286b68b

Please sign in to comment.