Implemented a slue of new functions to interact with the realms API #40

IanTapply22 · 2023-10-21T04:01:43Z

This PR implements a handful of new functions to interact with even more parts of the Minecraft realms API—all the way from banning players to deleting a realm with the specified ID. You can find the added functionality below:

Bedrock & Java

Get realm subscription info
Get detailed realm subscription info
Change active realm slot
Change realm name and description
Delete realm

Bedrock

Reset realm
Update realm configuration
Remove realm invite
OP realm player
DEOP realm player
Ban player from the realm
Unban player from the realm
Remove realm from joined list
Update forced texture pack rule
Update realm default permission
Update realm player permission

Feel free to leave suggestions or comments if you need anything fixed, added, or updated. Thanks

Copied bedrock realm API functions that also apply to Java over to Java Updated Realm object and BedrockRealmAPI class

IanTapply22 · 2023-10-21T04:05:27Z

Are we wanting to add test cases for all of these calls?

extremeheat

Thanks for working on this. Left some comments, but yes tests would be good for API calls that are expected to return something from the server, so we know what data we're working with.

These new functions would also need to be added to the doc, with explicit information on what they return.

cc @LucienHH if you have anything to add

src/bedrock/api.js

src/structures/Realm.js

src/bedrock/api.js

IanTapply22 · 2023-10-21T15:38:39Z

Sounds good! Thank you for the feedback and the review. Expect everything to be pushed by the end of today. (in ~4 hours from now max)

Removed removeAllRealmPlayers function due to invalid request Added params to methods in Realm.js Created tests and responses for the new functions Added documentation for the new functions

IanTapply22 · 2023-10-21T20:00:28Z

For now, I'm not pushing anything related to removing all realm players for now. There seems to be an issue with setting values as null in the body of the requests.

I will be creating another PR for this issue to address it better and to keep it separated from here.

src/bedrock/api.js

src/java/api.js

docs/API.md

Fixed body of userPermission request Moved functions that are the same into RealmAPI class Renamed removePlayerFromRealm uuid param to xuid

IanTapply22 · 2023-10-22T03:50:58Z

Fixed everything there, there are a couple of small things that still need to be fixed but I already have another PR cooking up to address them.

test/bedrockAPI.js

docs/API.md

Changed configuration parameter to be an Object instead of a String

IanTapply22 · 2023-10-22T21:04:50Z

If you could just make one big list of changes that need to be made it'd be greatly appreciated. It's nice to just have one big push of fixes then the commit history doesn't get all clogged unless we're doing a rebase when merging.

extremeheat · 2023-10-22T21:06:09Z

Don't worry about the PR commits. It will be squashed on merge.

LucienHH · 2023-10-22T21:12:08Z

docs/API.md

+Updates a Realms configuration. This can be gamerules or general Realm settings
+
+```js
+const configuration = { description:{description: "",name: option:{slotName:"Test",pvp:true,spawnAnimals:true,spawnMonster:true,spawnNPCs:true,spawnProtection:0,commandBlocks:false,forceGameMode:false,gameMode:0,difficulty:2,worldTemplateId:-1,worldTemplateImage:"",adventureMap:false,resourcePackHash:null,incompatibilities:[],versionRef:"",versionLock:false,cheatsAllowed:true,texturePacksRequired:true,timeRequest:null,enabledPacks:{resourcePacks:[""],behaviorPacks:[""]},customGameServerGlobalProperties:null,worldSettings:{sendcommandfeedback:{type:0,value:true}commandblocksenabled:{type:0,value:true},dodaylightcycle:{type:0,value:true},randomtickspeed:{type:1,value:3},naturalregeneration:{type:0,value:true},showtags:{type:0,value:true},commandblockoutput:{type:0,value:true},dofiretick:{type:0,value:false},maxcommandchainlength:{type:1,value:65535},falldamage:{type:0,value:true},tntexplodes:{type:0,value:true},drowningdamage:{type:0,value:true},domobloot:{type:0,value:true},domobspawning:{type:0,value:true},showbordereffect:{type:0,value,:true},showdeathmessages:{type:0,value:true},respawnblocksexplode:{type:0,value:true},doweathercycle:{type:0,value:true},doentitydrops:{type:0,value:true},doimmediaterespawn:{type:0,value:true},freezedamage:{type:0,value:true},pvp:{type:0,value:true},keepinventory:{type:0,value:false},doinsomnia:{type:0,value:true},mobgriefing:{type:0,value:true},dotiledrops:{type:0,value:true},firedamage:{type:0,value:true},functioncommandlimit:{type:1,value:10000},spawnradius:{type:1,value:25},showcoordinates:{type:0,value:true}}}}}


Maybe out of scope for this PR but providing some sort of config builder would make it a lot easier to interact with the API here. I.e.

const { RealmConfigBuilder } = require('prismarine-realms') const config = new RealmConfigBuilder() .setName('') .setDescription('') .addWorldSettings( { name: 'dofiretick', value: true }, { name: 'domobloot', value: false} ) api.changeRealmConfiguration(config)

Yep! I was thinking the same thing. It was really bugging me with the large JSON code block. I'll open another PR relatively soon sometime this week, or I'll just push it along with the next PR I have as a draft right now.

You can remove this function from this PR and add it to a later one if it's not ready

IanTapply22 · 2023-10-22T21:15:32Z

If you have any feedback for anything else that is out of scope or that you think doesn't belong in this PR just let me know and I'll create another PR. Right now I'm just trying to get a good baseline to start from to expand further and improve.

extremeheat

The purpose of prismarine realms isn't to be an basic API wrapper per se but provide a stable high level lib. If we have to put out a breaking change if the backend changes its data format then it's no good.

So if we either return, store or expose data, it needs to be explicit. If something is supposedly void then generally there should not be any return value in the method.

IanTapply22 · 2023-10-22T22:16:18Z

So I should be making custom types for responses for every function that returns something other than void in index.ts?

extremeheat · 2023-10-22T22:22:02Z

Yes, either don't return anything or doc what is returned

Updated docs to reflect type changes Formatted what functions return to reflect their custom types

IanTapply22 · 2023-10-24T19:57:29Z

Any other changes that need to be made?

extremeheat

Left some comments about API. Some of these things should be exceptions. Otherwise if a return value is expected, like status of success, then the example code needs to handle the false cases when calling functions like .open().

extremeheat · 2023-10-25T19:05:08Z

docs/API.md


 Restores a Realm from a backup

 ```js
 await api.restoreRealmFromBackup('1234567', '1', '1970-01-01T00:00:00.000Z')
 ```

-No output
+Either 'Retry again later' or 'true'. Always seems to return 'Retry again later' on the first try.


Shouldn't this be handled internally with an exception? This doesn't seem like good exposed API.

extremeheat · 2023-10-25T19:05:40Z

docs/API.md

+
+### removePlayerFromRealm
+
+(realmId: string, xuid: string) => Promise\<Realm>


Why specifically return a Realm here?

In the bedrock Realm API docs, it states it returns all information about the Realm. Should we not be returning all the Realm's information as states in the API docs?

Nevermind, ignore that. I understand now. Thank you

extremeheat · 2023-10-25T19:06:14Z

docs/API.md

+Updates a Realms configuration. This can be gamerules or general Realm settings
+
+```js
+const configuration = { description:{description: "",name: option:{slotName:"Test",pvp:true,spawnAnimals:true,spawnMonster:true,spawnNPCs:true,spawnProtection:0,commandBlocks:false,forceGameMode:false,gameMode:0,difficulty:2,worldTemplateId:-1,worldTemplateImage:"",adventureMap:false,resourcePackHash:null,incompatibilities:[],versionRef:"",versionLock:false,cheatsAllowed:true,texturePacksRequired:true,timeRequest:null,enabledPacks:{resourcePacks:[""],behaviorPacks:[""]},customGameServerGlobalProperties:null,worldSettings:{sendcommandfeedback:{type:0,value:true}commandblocksenabled:{type:0,value:true},dodaylightcycle:{type:0,value:true},randomtickspeed:{type:1,value:3},naturalregeneration:{type:0,value:true},showtags:{type:0,value:true},commandblockoutput:{type:0,value:true},dofiretick:{type:0,value:false},maxcommandchainlength:{type:1,value:65535},falldamage:{type:0,value:true},tntexplodes:{type:0,value:true},drowningdamage:{type:0,value:true},domobloot:{type:0,value:true},domobspawning:{type:0,value:true},showbordereffect:{type:0,value,:true},showdeathmessages:{type:0,value:true},respawnblocksexplode:{type:0,value:true},doweathercycle:{type:0,value:true},doentitydrops:{type:0,value:true},doimmediaterespawn:{type:0,value:true},freezedamage:{type:0,value:true},pvp:{type:0,value:true},keepinventory:{type:0,value:false},doinsomnia:{type:0,value:true},mobgriefing:{type:0,value:true},dotiledrops:{type:0,value:true},firedamage:{type:0,value:true},functioncommandlimit:{type:1,value:10000},spawnradius:{type:1,value:25},showcoordinates:{type:0,value:true}}}}}


You can remove this function from this PR and add it to a later one if it's not ready

extremeheat · 2023-10-25T19:06:43Z

docs/API.md

+
+### opRealmPlayer
+
+(realmId: string, uuid: string) => Promise\<Realm>


Why return Realm here?

Same question as here

extremeheat · 2023-10-25T19:06:52Z

docs/API.md

+
+### deopRealmPlayer
+
+(realmId: string, uuid: string) => Promise\<Realm>


Same comment as above. This does but banPlayerFromRealm doesn't return Realm.

extremeheat · 2023-10-25T19:08:01Z

docs/API.md


 Opens a Realm. Allows players to join

 ```js
 await realm.open()
 ```

-No output
+True if the world has opened


Can't this be an exception? Otherwise example code needs to handle the false case.

There is no false case, as stated here it doesn't return false, it returns the retry again later string. Should we be returning false from this function considering it's basically false if it says retry again later.

I also understand this too, sorry about that.

extremeheat · 2023-10-29T17:50:22Z

So after a second review, some of the doc/types you updated aren't things changed in the code, so instead of making changes there per my previous comments (about how we should throw), what you can do is simply revert those changes (like changes to .open()). We can handle those later, so we can get this merged quicker.

Also, @LucienHH do you think the configuration object will change or break in the future? If so we should move that out of the PR until some abstraction is implemented there. If not then I think it's ok if we just leave it as an dynamic object.

LucienHH · 2023-11-05T11:36:01Z

Also, @LucienHH do you think the configuration object will change or break in the future? If so we should move that out of the PR until some abstraction is implemented there. If not then I think it's ok if we just leave it as an dynamic object.

The config can change from update to update so should definitely be abstracted away, funnily enough the config has already changed from the one in this PR.

rom1504 · 2023-12-17T18:39:32Z

What is the status of this PR? what's missing to finish it ?

rom1504 · 2023-12-31T13:07:43Z

@LucienHH @extremeheat what do you think on this PR?

extremeheat

LGTM, I think previous my comments about API design are not worth blocking otherwise good PR. There are some useful additions here, thanks @IanTapply22 for the work on this

extremeheat · 2024-01-09T22:25:46Z

I commented out the changeRealmConfiguration method since that's not stable API, we can handle this in another PR

extremeheat · 2024-01-12T22:38:13Z

Thanks for the work on this. We can discuss the remaining changes in the other PR. I'll merge so we can resolve the PR backlog.

IanTapply22 added 3 commits October 20, 2023 17:43

Added near full coverage of bedrock realm API (missing misc)

5e4378d

Removed some unneeded returning of realm object

7c4f24e

Copied bedrock realm API functions that also apply to Java over to Java Updated Realm object and BedrockRealmAPI class

Fixed linting failure

9840b7a

extremeheat requested changes Oct 21, 2023

View reviewed changes

src/bedrock/api.js Show resolved Hide resolved

src/structures/Realm.js Outdated Show resolved Hide resolved

src/bedrock/api.js Outdated Show resolved Hide resolved

Renamed texture pack required function

6c6afca

Removed removeAllRealmPlayers function due to invalid request Added params to methods in Realm.js Created tests and responses for the new functions Added documentation for the new functions

IanTapply22 requested a review from extremeheat October 21, 2023 20:02

Removed removeAllRealmPlayers from table of contents

33bfe53

LucienHH reviewed Oct 22, 2023

View reviewed changes

src/bedrock/api.js Outdated Show resolved Hide resolved

src/bedrock/api.js Outdated Show resolved Hide resolved

src/java/api.js Outdated Show resolved Hide resolved

docs/API.md Outdated Show resolved Hide resolved

Renamed removeRealmInvite function

abb5dfe

Fixed body of userPermission request Moved functions that are the same into RealmAPI class Renamed removePlayerFromRealm uuid param to xuid

IanTapply22 requested a review from LucienHH October 22, 2023 03:50

extremeheat reviewed Oct 22, 2023

View reviewed changes

test/bedrockAPI.js Outdated Show resolved Hide resolved

extremeheat reviewed Oct 22, 2023

View reviewed changes

docs/API.md Outdated Show resolved Hide resolved

Made detailed a param for getSubscriptionInfo

4b30ccf

Changed configuration parameter to be an Object instead of a String

IanTapply22 requested a review from extremeheat October 22, 2023 21:04

No need for a custom configuration constructor

84caa72

LucienHH reviewed Oct 22, 2023

View reviewed changes

extremeheat reviewed Oct 22, 2023

View reviewed changes

IanTapply22 added 3 commits October 22, 2023 19:27

Fixed missing type returns in index.ts

ebfee8c

Updated docs to reflect type changes Formatted what functions return to reflect their custom types

Fixed lint fail

009bfd1

Fixed failing tests

8716174

IanTapply22 requested a review from extremeheat October 23, 2023 12:57

IanTapply22 requested a review from LucienHH October 23, 2023 12:57

extremeheat reviewed Oct 25, 2023

View reviewed changes

extremeheat approved these changes Jan 9, 2024

View reviewed changes

comment out changeRealmConfiguration method

1151c74

extremeheat mentioned this pull request Jan 9, 2024

Add support for MCBE Preview Realms #44

Merged

extremeheat merged commit 866ce6a into PrismarineJS:master Jan 12, 2024
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implemented a slue of new functions to interact with the realms API #40

Implemented a slue of new functions to interact with the realms API #40

IanTapply22 commented Oct 21, 2023 •

edited

Loading

IanTapply22 commented Oct 21, 2023 •

edited

Loading

extremeheat left a comment

IanTapply22 commented Oct 21, 2023

IanTapply22 commented Oct 21, 2023

IanTapply22 commented Oct 22, 2023

IanTapply22 commented Oct 22, 2023

extremeheat commented Oct 22, 2023

LucienHH Oct 22, 2023

IanTapply22 Oct 22, 2023

extremeheat Oct 25, 2023

IanTapply22 commented Oct 22, 2023

extremeheat left a comment

IanTapply22 commented Oct 22, 2023

extremeheat commented Oct 22, 2023

IanTapply22 commented Oct 24, 2023

extremeheat left a comment

extremeheat Oct 25, 2023

extremeheat Oct 25, 2023

IanTapply22 Oct 25, 2023

IanTapply22 Oct 25, 2023

extremeheat Oct 25, 2023

extremeheat Oct 25, 2023

IanTapply22 Oct 25, 2023

extremeheat Oct 25, 2023

extremeheat Oct 25, 2023

IanTapply22 Oct 25, 2023

IanTapply22 Oct 25, 2023

extremeheat commented Oct 29, 2023

LucienHH commented Nov 5, 2023

rom1504 commented Dec 17, 2023

rom1504 commented Dec 31, 2023

extremeheat left a comment

extremeheat commented Jan 9, 2024

extremeheat commented Jan 12, 2024


		### removePlayerFromRealm

		(realmId: string, xuid: string) => Promise\<Realm>


		### opRealmPlayer

		(realmId: string, uuid: string) => Promise\<Realm>


		### deopRealmPlayer

		(realmId: string, uuid: string) => Promise\<Realm>

Implemented a slue of new functions to interact with the realms API #40

Implemented a slue of new functions to interact with the realms API #40

Conversation

IanTapply22 commented Oct 21, 2023 • edited Loading

Bedrock & Java

Bedrock

IanTapply22 commented Oct 21, 2023 • edited Loading

extremeheat left a comment

Choose a reason for hiding this comment

IanTapply22 commented Oct 21, 2023

IanTapply22 commented Oct 21, 2023

IanTapply22 commented Oct 22, 2023

IanTapply22 commented Oct 22, 2023

extremeheat commented Oct 22, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IanTapply22 commented Oct 22, 2023

extremeheat left a comment

Choose a reason for hiding this comment

IanTapply22 commented Oct 22, 2023

extremeheat commented Oct 22, 2023

IanTapply22 commented Oct 24, 2023

extremeheat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

extremeheat commented Oct 29, 2023

LucienHH commented Nov 5, 2023

rom1504 commented Dec 17, 2023

rom1504 commented Dec 31, 2023

extremeheat left a comment

Choose a reason for hiding this comment

extremeheat commented Jan 9, 2024

extremeheat commented Jan 12, 2024

IanTapply22 commented Oct 21, 2023 •

edited

Loading

IanTapply22 commented Oct 21, 2023 •

edited

Loading