MongoSK Skript Tutorial

[_omga]

BEFORE READING:

• Currently, MongoSK is conflicting with various features of skript. A notable feature you can't use with MongoSK installed is metadata. There is no known ETA of when this will be fixed.
• For MongoSK, you need 2 plugins. MongoSK and Skript.
• MongoDB does NOT support datatypes such as inventories, items, or mobs. Some datatypes MongoDB supports are booleans, integers, timestamps, doubles, strings, and arrays.
• MongoSK sometimes doesn't give an error when you get your syntax wrong! If your mongo doesn't work, try rechecking your syntax.
• This is a LONG tutorial. Get comfortable, stop whenever you want to, and learn MongoSK!

INTRODUCTION:

With the amount of people thinking/wanting to use MongoSK increasing on Minehut, I thought I would make a little tutorial. The addition of MongoSK gives us the option to store variables and data externally instead of using the classic variables.csv. This tutorial will go over mostly everything you need to know to make a server using MongoSK.

MONGO INFORMATION:

In order to use MongoSK, you have to have a cluster you can connect to and store data in.

You can create a free cluster Here.

VIEWING MONGO DATA:

In order to view the data that gets stored, you have to have a MongoDB Viewer. The viewer that I use is the MongoDB Compass, created by MongoDB. You can download it Here.

STEPS TO CREATE CLUSTER:

1. Head to the MongoDB Atlas website and create an account.
2. You should have been brought to a dashboard-esk page. Click on "Organizations" on the left hand side of the screen.
3. Click "Create an Organization".
4. Name your organization anything you want. Choose MongoDB Atlas as the Cloud Service.
5. [Optional] Add whoever you want to the organization.
6. Click "New Project" in the upper right hand side of the screen.
7. Name your project.
8. [Optional] Add whoever you want to the project.
9. Click "Build a Cluster" in the middle of the screen.
10. Choose the third option "Shared Clusters" for a free cluster. If you are paying for a cluster, choose either option one or two.
11. Leave Global Cloud Configuration with its default parameters. For Cloud Provider select "AWS". For the region, select the one which is closest to you. Leave the cluster tier as is, as well as the additional settings. Name the cluster whatever you want.
12. Click the "Connect" button. It is next to "Metrics".
13. For the connection IP address, choose the third option, "Allow Access from Anywhere". Leave the IP address as the default parameter and click "Add IP Address". For the database user, select a name for your user. Then select a password. REMEMBER THESE TWO PIECES OF INFO! Then click "Create Database User".
14. You have just created a mongo cluster! I will explain soon how to get the URI of this cluster.

THE FORMAT OF MONGO:

Cluster (what you should have just made!) -> Database -> Collection -> Documents (documents that store the actual data!)

SYNTAX:

In this tutorial, I will be referencing the MongoSK syntax, so I think it is important to learn how to read syntax. Reading syntax is not an essential part of skript, so if you do not understand this, don't worry, as I will be giving code examples.

• %% = an object/objects (e.g. player(s) or string(s))
• [] = optional, meaning it is not mandatory
• (option 1|option 2) = interchangeable, but only one can be used

EXAMPLES:

• close [mongo[db]] connection [of] %mongoclient% | Syntax
• close connection "mongo" | Correct Usage
• close mongodb connection "mongo" | Correct Usage
   
• (all|every) mongo[db] documents (in|of) %mongocollection% | Syntax
• all mongodb documents of "collection" | Correct Usage
• close mongodb connection "mongo" | Correct Usage

 

---

SETTING UP MONGOSK:

A small disclaimer before we start coding. For the mongo variables, I will be using what I call "Temp Global Variables" or "Ram Variables". That is what the "-" is before the start of the mongo variable ({-mongo::*}). You can read This forum post to learn how to enable ram variables. If you don't want to use ram variables, simply change "{-mongo::" to "{mongo::".

To start with MongoSK, we first have to create the mongo connection and client. We can do this with a load event, the Create Mongo Client effect, and the Mongo Client expression.

+ on load:
+	create a new mongo client to host "mongodb+srv://" named "mongo"
+	set {-mongo::client} to client named "mongo"

This code will create a new mongo client. Where "mongodb+srv://" is, you want to replace with your MongoDB connection. You can create a MongoDB connection link by navigating to the cluster you should have created earlier.

Click on the connect button, and you should be brought into a screen with a three options.
ALWAYS SELECT THE SECOND OPTION. As the bold text says, if you're doing MongoSK, select the second option "Connect Your Application". You will be brought to a screen containing the choice to choose a driver and it's version.

Leave it as it is (as Node.js v3.6 or later).

In the same screen, you should find a link you can copy. In the link, you will find that the "<password>" option is not filled, and is just a placeholder. Remember when we first made the cluster? Now you need the password + user. Replace the placeholder "<password>" with the password you created as you made your cluster. You can either replace or leave the placeholder "myFirstDatabase". If your username is NOT the name you used to create the cluster, change it to the name you used to create the cluster.

The way our code is right now, every time you reload the skript, it will create a new mongo connection. This will keep on stacking the mongo connections. Add the code below to fix this problem.

on load:
+	if {-mongo::*} is set:
+		close connection {-mongo::client}
+		delete {-mongo::*}
	create a new mongo client to host "mongodb+srv://" named "mongo"
	set {-mongo::client} to client named "mongo"

Next, we are going to connect more ram variables to different databases in our mongo cluster. For this tutorial, I will be using a database named "tutorialGens" for storing data for the gens section of this tutorial.

on load:
	if {-mongo::*} is set:
		close connection {-mongo::client}
		delete {-mongo::*}
	create a new mongo client to host "mongodb+srv://" named "mongo"
	set {-mongo::client} to client named "mongo"
+	set {-mongo::tutorialGens} to mongo database named "tutorialGens" with {-mongo::client}

Now that we have set all of our variables, we are ready to start messing with the data in mongo. I am going to be showing a very simple gens system that will help you understand MongoSK and all of its features. First, we need to start off with gen create command.

+ command gen.create (<string>) (<itemtype>) <itemtype>:
+	trigger:

+		send "Created gen %colored arg 1%"

The code above is a simple command. Head to This site to learn more about custom commands. Argument 1 is the gen name, argument 2 is the item drop type, and argument 3 is the blocktype. To identify different gens, I like to use an ID system (numeric). We are going to add the code for that system now.

command gen.create (<string>) (<itemtype>) <itemtype>:
	trigger:
+		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+		set {_documents::*} to all mongo documents in {_collection}
+		set {_size} to size of {_documents::*}
+		set {_lastDocument} to {_documents::%{_size}%}
+		set {_id} to "%value ""id"" of {_lastDocument}%" parsed as integer + 1
		send "Created gen %colored arg 1%"

In the newly added code, I set a new local variable to the collection named "gens" in the database "tutorialGens". The next lines are more advanced. In the next lines I first set a local list variable to all of the documents in the collection. I then get the last document from that list variable, so I know what the last used id is. I then set the ID variable to ("%value ""id"" of {_lastDocument}%" parsed as integer + 1). Even though the value "id" of documents is already an integer, it sometimes bugs out and doesn't return an integer. This is why I convert the value "id" to an integer and parse it as an integer. Then, I am just adding one to the id to make it the next usable ID.

Now that the server knows what to use as the ID of the gen, we have to code in the mongo document value setting. For this particular gens skript, I will be setting the #1 Name, #2 Itemtype drop, and #3 Blocktype.

command gen.create (<string>) (<itemtype>) <itemtype>:
	trigger:
		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
        set {_documents::*} to all mongo documents in {_collection}
		set {_size} to size of {_documents::*}
		set {_lastDocument} to {_documents::%{_size}%}
		set {_id} to "%value ""id"" of {_lastDocument}%" parsed as integer + 1
+		set {_newDocument} to new mongo document
+		set value "id" of {_newDocument} to {_id}
+		set value "name" of {_newDocument} to colored arg 1
+		set value "itemtype" of {_newDocument} to "%arg 2%"
+		set value "blocktype" of {_newDocument} to "%arg 3%"
+		save {_newDocument} in {_collection}
		send "Created gen %colored arg 1%"

Here, I am first setting a variable to a new mongo document. Next, I am continuously setting the values of the document to what I want. ID gets set to the next usable ID, the name gets set to the first argument, so on so forth. Notice how when I am setting the values I stringify (make a string) the itemtypes. This is because MongoDB does not support itemtypes as a datatype. Later on, when getting the itemtypes, we will have to reparse it as an itemtype. [Example: /gen.create (Example Generator 1) (diamond) diamond ore]

Great! We now have our first command out of three done! Next, I will be creating an edit drop command, where you can edit the gen drops. First, lets start out with the base command again.

+ command gen.edit <integer> <itemtype>:
+	trigger:

+		send "Edited the gen %arg 1%"

This is just a regular old base command... Argument 1 is the gen ID. Remember the ID system we created earlier? We're using it right now! We need the ID to fetch the correct mongo document. Argument 2 is the new item drop type. Lets move onto the actual editing. We first have to get the right document from the collection "gens".

command gen.edit <integer> <itemtype>:
	trigger:
+		set {_id} to arg 1
+		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+		set {_document} to first mongo document where "id" is {_id} in {_collection}
+		if {_document} is not set:
+			send "The gen ID %{_id}% is not set."
+			stop
		send "Editted the gen %{_id}%"

First, I am setting a variable to the ID (argument 1) for convenience purposes. Also, to make this tutorial shorter, I will not be explaining concepts that we have gone over in previous code. The line (set {_document} to first mongo document where "id" is {_id} in {_collection}) is new though. This expression gets the first document where the value of a document matches with another value. Then, we check if the document is not set. If it isn't, we send our standard "Not Set" message.

command gen.edit <integer> <itemtype>:
	trigger:
		set {_id} to arg 1
		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
		set {_document} to first mongo document where "id" is {_id} in {_collection}
		if {_document} is not set:
			send "The gen ID %{_id}% is not set."
			stop
+		set value "itemtype" of {_document} to "%arg 2%"
+		save {_document} in {_collection}
		send "Editted the gen %{_id}%"

Here, we are essentially editing the value of the document to argument two. Again, we have to save the document in the collection for it to update. Congrats! You just completed the gen edit command! [Example: /gen.edit 1 emerald]

For the delete command, I'm just going to skip forward to the actual deleting.

+ command gen.delete <integer>:
+	trigger:
+		set {_id} to arg 1
+		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+		set {_document} to first mongo document where "id" is {_id} in {_collection}
+		if {_document} is not set:
+			send "The gen ID %{_id}% is not set."
+			stop

+		send "Deleted the gen %{_id}%"

If you need explaining on how we get the correct document based off of IDs, check the command above this one, editing gens. Next, we are going to be actually deleting the generator from the mongo database.

command gen.delete <integer>:
	trigger:
		set {_id} to arg 1
		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
		set {_document} to first mongo document where "id" is {_id} in {_collection}
		if {_document} is not set:
			send "The gen ID %{_id}% is not set."
			stop
+		delete mongo document {_document} from {_collection}
		send "Deleted the gen %{_id}%"

This is just one more line of skript added. We added the Delete Mongo Document effect. This effect, well, deletes the mongo document. No need to save the document in the collection here! Congrats! You have completed the delete commands! [Example: /gen.delete 1] Next, I will be making a command that will give you a gen with all of the generator information.

First, lets start off with the start of the command and the id system.

+ command gen.give <integer>:
+	trigger:
+		set {_id} to arg 1
+		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+		set {_document} to first mongo document where "id" is {_id} in {_collection}
+		if {_document} is not set:
+			send "The gen ID %{_id}% is not set."
+			stop

+		send "Gave the gen %{_id}% to you."

Now, we have to actually give the player the item with the generator information. We can do this by calling the information from the database.

command gen.give <integer>:
	trigger:
		set {_id} to arg 1
		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
		set {_document} to first mongo document where "id" is {_id} in {_collection}
		if {_document} is not set:
			send "The gen ID %{_id}% is not set."
			stop
+		set {_name} to value "name" of {_document}
+		set {_itemtype} to value "itemtype" of {_document}
+		set {_blocktype} to value "blocktype" of {_document}
		send "Gave the gen %{_id}% to you."

The new code essentially uses the Mongo Value expression to get the values of what I need (name, itemtype, and blocktype). Now, let's make the actual item.

command gen.give <integer>:
	trigger:
		set {_id} to arg 1
		set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
		set {_document} to first mongo document where "id" is {_id} in {_collection}
		if {_document} is not set:
			send "The gen ID %{_id}% is not set."
			stop
		set {_name} to value "name" of {_document}
		set {_itemtype} to value "itemtype" of {_document}
		set {_blocktype} to value "blocktype" of {_document}
+		give player 1 of ("%{_blocktype}%" parsed as itemtype) named {_name} with lore " ", "&7Drops: &e%{_itemtype}%"
		send "Gave the gen %{_id}% to you."

We have 1 line of new code, where I am using the values I just set to create a fully formatted item. As you can see, I have to parsed the blocktype as an itemtype. This is because I originally stored it as a string because MongoDB does not support the datatype "itemtype". Congrats! You have completed the main commands for this tutorial! [Example: /gen.give 1] Now, moving onto the core gens code. I will be going through this code quicker now that you (hopefully) should have a basic understanding of MongoDB and MongoSK.

For detecting if the player's tool is a gen, I will be using item names. This is not a bad way to do it, but it also isn't the best. One known issue with this way is the whole system will break if you make more than one gen with the same name. You can make a more advanced method using NBT. I won't be going over that though. Lets start with creating the basic code.

+ on place:
+	set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+	loop all mongo documents in {_collection}:
+		uncolored name of tool is uncolored value "name" of loop-value
+		set {_id} to value "id" of loop-value
+		exit 1 loop

Looping all of the documents let me scan through each and every document in the collection named "gens". This will allow me to filter out the documents I don't want and get the ID of the one I do want. I am checking if the name of the player's tool is the same as the name of the document, and if it is, setting the ID variable to the value "id" of the document. I am then exiting the loop to completely stop the loop. For saving the playerdata (gen locations, gen amount, etc.), I will be using regular skript variables. This is to shorten the length of this tutorial, as it already is very long. With the information gained from this tutorial, you should be able to create your own.

on place:
	set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
	loop all mongo documents in {_collection}:
		uncolored name of tool is uncolored value "name" of loop-value
		set {_id} to value "id" of loop-value
		exit 1 loop
+	if {_id} is set:
+		set {player::%player's uuid%::gens} to 0 if {player::%player's uuid%::gens} is not set
+		set {player::%player's uuid%::maxgens} to 25 if {player::%player's uuid%::maxgens} is not set
+		if {player::%player's uuid%::gens} is less than {player::%player's uuid%::maxgens}:
+			add 1 to {player::%player's uuid%::gens}
+			add event-location to {player::%player's uuid%::genLocations::%{_id}%::*}
+			send "Placed gen."

Here, if the ID is set, meaning the player's tool IS a gen, we run standard generator add code. Checking if the player's gens is less than the max gens, adding 1 to the player's gen count, blah blah blah. The only thing different is I am setting the player's gens and max gens variables to their default values if they are not set. We have now completed the place event! You should now be able to place your generators!

Finally, for the last section of this tutorial, I will be making the items actually spew out of placed generators. For the item generation, we will be using an on join event as well as a while loop. Lets start with that.

on join:
	while player is online:

		wait 9 seconds

The reason why I am using an on join event and not looping all players every second is because the on join event is known to be more efficient. The key to this is the wait. If you don't add the wait, you might find that your server will crash very quickly after you join! How long you wait for is also how long it takes for each item to spawn!

on join:
	while player is online:
+		loop all indices of {player::%player's uuid%::genLocations::*}:
+			loop {player::%player's uuid%::genLocations::%loop-value%::*}:
+				set {_collection} to mongo collection named "gens" in {-mongo::tutorialGens}
+				set {_document} to first mongo document where "id" is "%loop-value-1%" parsed as integer in {_collection}
+				set {_itemdrop} to value "itemtype" of {_document}
+				drop 1 of "%{_itemdrop}%" parsed as itemtype at block above loop-value-2
		wait 9 seconds

The final stretch! In this newly added code, we are first looping the indices of the player's gen locations (gen IDs). Then, we are looping the locations of the gens with ID loop-value. We also have to get the data so we know what item to drop! As you can see, I did parse the itemtype value from the mongo document as an itemtype.

 

You have made it to the end of this MongoSK tutorial! Congrats! Hopefully, you should have a decent understanding of how MongoSK works. At least, enough to create a server with. It was fun writing this tutorial, I hope you enjoyed! If you have any questions, concerns, or issues, please feel free to reply to this topic or direct message me on Discord @ omega#1000.
[Please keep in mind this is NOT the best way to use MongoSK. The most efficient way of using MongoSK would be to load all data on server start, periodically save it, and save it when the server stops. This post was and is not a gens skript release. This post is a tutorial on how to use MongoSK.]

If you liked this tutorial, feel free to drop a like!

 

I have provided advaned examples of how a playerdata save / load should look in the ending code.
Ending Code: https://paste.md-5.net/ojebucevug.sql

 

Edited March 9, 2021 by _omga
Paginated

[emopediaMC]

Great detail, great for people who want to use mongo.

[_omga]

Thank you!

[_omga]

No problem!

[chillins]

Great work! 

[_Tarna_]

Cool and detailed tutorial! 

[Untreated]

Absolutely incredible tutorial. Great job.

[BurningBrimstone]

Great tutorial Omega!

Been considering learning MongoSk for a bit; definitely will be a good starting guide!

[MineralMiner]

Thanks! This looks really good if I ever want to use mongodb with my skripts.

[CoolProgrammer]

New definition of POG?

[emopediaMC]

15 minutes ago, CoolProgrammer said:

New definition of POG?

yes

[nicholxs]

Great tutorial!

[Tistay]

ok nerd

[pnguin]

Perfect tutorial!

[Romitou]

Thank you for your work!

[_omga]

Thank you!