From e8896187ff23ce9893b76f3f363e158986442c3e Mon Sep 17 00:00:00 2001 From: Xenmai Date: Sat, 23 Feb 2019 17:12:31 +0100 Subject: [PATCH 1/6] First Example Project Guide --- .../halloween-treasure-hunt.rst | 250 ++++++++++++++++++ source/docs/example-projects/index.rst | 15 ++ source/index.rst | 9 +- 3 files changed, 273 insertions(+), 1 deletion(-) create mode 100644 source/docs/example-projects/halloween-treasure-hunt.rst create mode 100644 source/docs/example-projects/index.rst diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst new file mode 100644 index 0000000..e6332b8 --- /dev/null +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -0,0 +1,250 @@ +======================= +Halloween Treasure Hunt +======================= + +.. contents:: Table of Contents + :local: + +Introduction +============ + +Welcome back to the **Denizen-for-Bukkit Docs**. This is our first example project, so we'll start with the basics. +This guide will cover the following topics: + +* Denizen objects and general syntax. +* Browsing through the documentation. +* Reloading scripts and debug modes. +* World script containers, events and context tags. +* Common script commands and arguments. +* Constructing tags with simple bases and modifiers. +* First contact with foreach loops. + +If you are not familiar with any of the concepts listed, we suggest revisiting the following tutorial documents: + +* :doc:`Section 1.3 - dScript Format ` +* :doc:`Section 2.1 - An Introduction to Tags ` +* :doc:`Section 2.2 - The Basics of Denizen Commands ` +* :doc:`Section 2.7 - Your First World Script ` +* foreach loops here + +This will help you make a better use of this example project, and follow its contents successfully. + +.. note:: + It is also recommended to have the `meta documentation `_ open in another tab while scripting this project, as we'll + need to check the syntax of events, commands and tags very often. + +First Steps +=========== + +Now let's jump (or slowly crawl) into the scripting process. In our case, we want to make a **Halloween Treasure +Hunt** event in our *Hub world*. We plan on manually placing some hidden pumpkins ourselves, and reward players for +finding (and left clicking) them. + +First of all, we'll need to create a *new script file* (for example ``Halloween_Treasure_Hunt.yml``) and build a world +script container which, as we know, will listen to events happening within our server. We just have to give it a name, +like ``Halloween_Treasure_Hunt``, and set the ``type:`` key to ``world``. In addition to this, we'll also enable debug +by setting the ``debug:`` key to ``true``. This will make our script print in the console everything it does and help +us solve errors. It is not needed, so we can just disable it later on. We'll now add an ``events:`` subkey, which will +in the end hold the executable code we're going to write. + +Our file with the script container looks like this: + +.. code-block:: dscript + :name: figure_1_1 + :linenos: + :emphasize-lines: 1-4 + + Halloween_Treasure_Hunt: + type: world + debug: true + events: + +.. rst-class:: figurecaption + +**Figure 1.1** Our starting world script container + +It's worth noting that Denizen scripts follow **YAML**'s indentation rules, with either *2 or 4-space tabs*. Many text +editors can be used for writing these scripts, but we personally prefer **Notepad++**. You just have to make sure the +tabs are replaced with actual spaces. There's a settings option in that automatically does that for us, so no problem. + +Now we need to find an event that fits our case. Looking through the *event list* documentation, ``on player clicks +block`` looks like our best bet. We just have to adjust it for our specific use case by adding *optional* arguments. +According to the event syntax, it accepts a click type, a material and an area, which will just be ``left``, +``pumpkin`` and ``in Hub`` respectively. + +.. note:: + This tutorial assumes our *Hub world* is in fact called ``Hub``. + +We'll just make sure it works for now, so we add it under the events key and end the line with a ``:``. Inside this +event we can place our first command. A good option for testing purposes is just to show a word in *chat*. The command +for this is :guilabel:`narrate`. As the documentation explains, its syntax is very simple, only requiring a message +argument. We feel the hype, so we'll go with a ``- narrate "yay"``. + +Our script should be the following at this point: + +.. code-block:: dscript + :name: figure_1_2 + :linenos: + :emphasize-lines: 5,6 + + Halloween_Treasure_Hunt: + type: world + debug: true + events: + on player left clicks pumpkin in Hub: + - narrate "yay" + +.. rst-class:: figurecaption + +**Figure 1.2** Our world script with a specific event + +It's time to *save* the script file, *reload* scripts ingame with ``/denizen reload scripts`` and *trigger the event* +by left clicking a pumpkin block in our Hub world. We should now be able to see a cute little ``yay`` in chat, along +with some debug information in the console, just as we expected. That's great, but we also have to *test* and make +sure the event is not being triggered when clicking other types of blocks, when right clicking, or when clicking in +another world. + +Core Functionality +================== + +We're ready to move further ahead and actually give a *reward* to the player clicking the block. Since we're nice +server owners, the prize will be a free *diamond*. This is where the :guilabel:`give` command comes in handy. Its +*syntax* specifies a single required argument: ``[money/xp/|...]``. In our case, what we want to give the player +is a diamond item, so we can ignore the *money* and *xp* options. + +.. note:: + When reading command documentation, It's important to keep in mind that anything inside ``< >`` is *not literal* + and needs to be replaced. Arguments enclosed in ``[ ]`` are *required*, while ``( )`` means an argument is + *optional*. The ``/`` symbol separates argument *options*, meaning you have to choose one of them. + +Let's go ahead and specify ``diamond`` as the first argument of our give command. We don't have to worry about who to +give the diamond to, as the command will target the linked player by default. That is, the player that triggered the +event. The full command line will then be ``- give diamond``. + +Now it's time to make sure it works. After *saving* and *reloading* scripts again, it should be giving us a *diamond* +every time we click the *pumpkin*. While players will totally love this, we should probably avoid giving out unlimited +diamonds. That's easy to fix though, we just have to *remove* the pumpkin once it's clicked. If we do it before even +giving out the reward, we'll make sure it won't be clicked twice. + +For this, we'll use the :guilabel:`modifyblock` command, which lets us specify a *location* and a *material*. Now we +only need to know which location was clicked by the player. Time to make use of *context* tags! This kind of tags are +event specific and will let us retrieve useful information from said event. If we check again the event's +documentation, we can see it has a ```` tag available, which is just what we needed for the first +argument. The material, on the other hand, will be just ``air`` as we want to remove the original pumpkin. The full +command line will then be ``- modifyblock air``. + +Our script with these new commands should look like this: + +.. code-block:: dscript + :name: figure_1_3 + :linenos: + :emphasize-lines: 7,8 + + Halloween_Treasure_Hunt: + type: world + debug: true + events: + on player left clicks pumpkin in Hub: + - narrate "yay" + - modifyblock air + - give diamond + +.. rst-class:: figurecaption + +**Figure 1.3** Our world script with core functionality + +Rinse and repeat: save, reload scripts and do a quick test. Amazing! This deserves a "yay". Speaking of yays… we don't +need to narrate ``yay`` for testing purposes anymore, so we better change it to something more informative. Something +like ``- narrate "You've found a pumpkin! Here's your reward!"`` sounds like the way to go. + +Topping It Off +============== + +Let's make it even more fun. What if *jack o' lanterns* gave a diamond to *every online player*? Yeah, we can make +that happen too! Let's start by making a copy of the event we already have and its contents. We should now change the +``pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack o' lantern blocks. + +.. note:: + There are other ways to achieve this event logic. For example, we could use a single general event that triggers + for every block clicked, and filter the needed blocks with logic, such as **if/else if/else** trees or **choose** + commands. In this guide though, two separate events will be used as we feel that can help keep it simple without + losing functionality. + +Inside the event, we need to repeat the give command once per player. How to do that? You've guessed it, a loop! In +our case, to wrap the :guilabel:`give` command with a :guilabel:`foreach` loop is all we need. This loop takes a +*list* when it starts and executes some commands for *every object* on the list. We just need to feed it the list of +online players, which can be accessed through ````. + +Inside the :guilabel:`foreach` command block, we can retrieve the currently *looped object* with ````. +We'll use this player object to tell the give command who to target. This can easily be done by setting the linked +player of said command, possible thanks to the ``player:`` argument. Feed this argument the tag we've just mentioned +and we're ready to go. + +Here's the complete second event: + +.. code-block:: dscript + :name: figure_1_4 + :linenos: + :emphasize-lines: 10-14 + + Halloween_Treasure_Hunt: + type: world + debug: true + events: + on player left clicks pumpkin in Hub: + - narrate "You've found a pumpkin! Here's your reward!" + - modifyblock air + - give diamond + + on player left clicks jack_o_lantern in Hub: + - narrate "You've found a pumpkin! Here's your reward!" + - modifyblock air + - foreach : + - give diamond player: + +.. rst-class:: figurecaption + +**Figure 1.4** Our world script with a second event + +We also have to let all the players know who their new *hero* is, and instead of narrating to them one by one, we can +just announce the message to the whole server. According to the :guilabel:`announce` command syntax, it only requires one +argument: the message. We just want to know the *name* of the player who found the hidden block , but that's not a +problem at all. As we already know, all events related to players let you access their linked player with the +```` tag. In our case, we need their actual name, so we will just add ``.name`` to the tag. + +.. note:: + Double quotes (``" "``) are used to group text so it's treated as a *single argument*. This is specially useful for + commands based on chat text, such as :guilabel:`narrate` and :guilabel:`announce`. + +Our command would be as easy as ``- announce " has found a jack o' lantern. Everybody gets a reward!"``. +We only have to replace the old narrate command in the second event with our new announce. Now we just have to make +sure it *works as intended* after reloading, and finally set the ``debug:`` key to ``false`` so only error messages +are shown. No more console *spam*! + +Finally, this is the full script that we've created: + +.. code-block:: dscript + :name: figure_1_5 + :linenos: + :emphasize-lines: 11 + + Halloween_Treasure_Hunt: + type: world + debug: false + events: + on player left clicks pumpkin in Hub: + - narrate "You've found a pumpkin! Here's your reward!" + - modifyblock air + - give diamond + + on player left clicks jack_o_lantern in Hub: + - announce " has found a jack o' lantern. Everybody gets a reward!" + - modifyblock air + - foreach : + - give diamond player: + +.. rst-class:: figurecaption + +**Figure 1.5** Our world script, finally complete + +This should be it for now. Enjoy your brand new **Halloween Treasure Hunt** event and *happy scripting*! \ No newline at end of file diff --git a/source/docs/example-projects/index.rst b/source/docs/example-projects/index.rst new file mode 100644 index 0000000..086133d --- /dev/null +++ b/source/docs/example-projects/index.rst @@ -0,0 +1,15 @@ +================ +Example Projects +================ + +This section is dedicated to documents guiding you through example projects, which are useful for putting together +everything you've learnt in the Denizen tutorial documents. + +Contents +======== + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + halloween-treasure-hunt diff --git a/source/index.rst b/source/index.rst index 9e8e152..db555b9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -34,12 +34,19 @@ Contents docs/basics-of-scripting/index docs/more-on-npcs/index +.. toctree:: + :maxdepth: 2 + :titlesonly: + :caption: Do It Yourself + + docs/example-projects/index + .. toctree:: :maxdepth: 2 :titlesonly: :caption: References - docs/glossary + docs/glossary Updates to This Text Tutorial ============================= From 762b8177e77f9194ef7219dee6532a3e5d79e9ca Mon Sep 17 00:00:00 2001 From: Xenmai Date: Mon, 25 Mar 2019 18:59:10 +0100 Subject: [PATCH 2/6] Fix Paragraph --- .../halloween-treasure-hunt.rst | 17 +++++++++-------- source/docs/example-projects/index.rst | 2 +- source/index.rst | 2 +- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst index e6332b8..638c6a5 100644 --- a/source/docs/example-projects/halloween-treasure-hunt.rst +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -30,8 +30,9 @@ If you are not familiar with any of the concepts listed, we suggest revisiting t This will help you make a better use of this example project, and follow its contents successfully. .. note:: - It is also recommended to have the `meta documentation `_ open in another tab while scripting this project, as we'll - need to check the syntax of events, commands and tags very often. + It is also recommended to have the `meta documentation `_ open in + another tab while scripting this project, as we'll need to check the syntax of events, commands and tags very + often. First Steps =========== @@ -165,10 +166,10 @@ that happen too! Let's start by making a copy of the event we already have and i ``pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack o' lantern blocks. .. note:: - There are other ways to achieve this event logic. For example, we could use a single general event that triggers - for every block clicked, and filter the needed blocks with logic, such as **if/else if/else** trees or **choose** - commands. In this guide though, two separate events will be used as we feel that can help keep it simple without - losing functionality. + There are other ways to achieve the same result. For example, a single general event that is triggered for every + block clicked could be used. This would mean filtering the needed blocks with logic afterwards, usually with + **if/else if/else** trees or **choose** commands. In this guide though, two separate events will be used as that + can help keep it simple without functionality. Inside the event, we need to repeat the give command once per player. How to do that? You've guessed it, a loop! In our case, to wrap the :guilabel:`give` command with a :guilabel:`foreach` loop is all we need. This loop takes a @@ -207,8 +208,8 @@ Here's the complete second event: **Figure 1.4** Our world script with a second event We also have to let all the players know who their new *hero* is, and instead of narrating to them one by one, we can -just announce the message to the whole server. According to the :guilabel:`announce` command syntax, it only requires one -argument: the message. We just want to know the *name* of the player who found the hidden block , but that's not a +just announce the message to the whole server. According to the :guilabel:`announce` command syntax, it only requires +one argument: the message. We just want to know the *name* of the player who found the hidden block , but that's not a problem at all. As we already know, all events related to players let you access their linked player with the ```` tag. In our case, we need their actual name, so we will just add ``.name`` to the tag. diff --git a/source/docs/example-projects/index.rst b/source/docs/example-projects/index.rst index 086133d..0c5aaee 100644 --- a/source/docs/example-projects/index.rst +++ b/source/docs/example-projects/index.rst @@ -3,7 +3,7 @@ Example Projects ================ This section is dedicated to documents guiding you through example projects, which are useful for putting together -everything you've learnt in the Denizen tutorial documents. +everything you've learned in the Denizen tutorial documents. Contents ======== diff --git a/source/index.rst b/source/index.rst index db555b9..a3d6baa 100644 --- a/source/index.rst +++ b/source/index.rst @@ -46,7 +46,7 @@ Contents :titlesonly: :caption: References - docs/glossary + docs/glossary Updates to This Text Tutorial ============================= From 136253d671633a4565568972297866c3f431e270 Mon Sep 17 00:00:00 2001 From: Xenmai Date: Tue, 26 Mar 2019 00:09:55 +0100 Subject: [PATCH 3/6] Improve the document --- .../halloween-treasure-hunt.rst | 104 ++++++++---------- 1 file changed, 47 insertions(+), 57 deletions(-) diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst index 638c6a5..396de82 100644 --- a/source/docs/example-projects/halloween-treasure-hunt.rst +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -1,6 +1,6 @@ -======================= -Halloween Treasure Hunt -======================= +========================== +1. Halloween Treasure Hunt +========================== .. contents:: Table of Contents :local: @@ -8,8 +8,7 @@ Halloween Treasure Hunt Introduction ============ -Welcome back to the **Denizen-for-Bukkit Docs**. This is our first example project, so we'll start with the basics. -This guide will cover the following topics: +In this first example project, we'll start with the basics. The following topics will be covered: * Denizen objects and general syntax. * Browsing through the documentation. @@ -25,7 +24,7 @@ If you are not familiar with any of the concepts listed, we suggest revisiting t * :doc:`Section 2.1 - An Introduction to Tags ` * :doc:`Section 2.2 - The Basics of Denizen Commands ` * :doc:`Section 2.7 - Your First World Script ` -* foreach loops here +* **[TODO: Add FOREACH section reference]** This will help you make a better use of this example project, and follow its contents successfully. @@ -34,8 +33,8 @@ This will help you make a better use of this example project, and follow its con another tab while scripting this project, as we'll need to check the syntax of events, commands and tags very often. -First Steps -=========== +1. First Steps +============== Now let's jump (or slowly crawl) into the scripting process. In our case, we want to make a **Halloween Treasure Hunt** event in our *Hub world*. We plan on manually placing some hidden pumpkins ourselves, and reward players for @@ -43,35 +42,28 @@ finding (and left clicking) them. First of all, we'll need to create a *new script file* (for example ``Halloween_Treasure_Hunt.yml``) and build a world script container which, as we know, will listen to events happening within our server. We just have to give it a name, -like ``Halloween_Treasure_Hunt``, and set the ``type:`` key to ``world``. In addition to this, we'll also enable debug -by setting the ``debug:`` key to ``true``. This will make our script print in the console everything it does and help -us solve errors. It is not needed, so we can just disable it later on. We'll now add an ``events:`` subkey, which will -in the end hold the executable code we're going to write. +like ``Halloween_Treasure_Hunt``, and set the ``type:`` key to ``world``. In addition to this, we'll also add an +``events:`` subkey, which will in the end hold the executable code we're going to write. Our file with the script container looks like this: .. code-block:: dscript - :name: figure_1_1 + :name: figureDIY_1_1 :linenos: - :emphasize-lines: 1-4 + :emphasize-lines: 1-3 Halloween_Treasure_Hunt: type: world - debug: true events: .. rst-class:: figurecaption **Figure 1.1** Our starting world script container -It's worth noting that Denizen scripts follow **YAML**'s indentation rules, with either *2 or 4-space tabs*. Many text -editors can be used for writing these scripts, but we personally prefer **Notepad++**. You just have to make sure the -tabs are replaced with actual spaces. There's a settings option in that automatically does that for us, so no problem. - Now we need to find an event that fits our case. Looking through the *event list* documentation, ``on player clicks block`` looks like our best bet. We just have to adjust it for our specific use case by adding *optional* arguments. According to the event syntax, it accepts a click type, a material and an area, which will just be ``left``, -``pumpkin`` and ``in Hub`` respectively. +``carved_pumpkin`` and ``in Hub`` respectively. .. note:: This tutorial assumes our *Hub world* is in fact called ``Hub``. @@ -84,15 +76,14 @@ argument. We feel the hype, so we'll go with a ``- narrate "yay"``. Our script should be the following at this point: .. code-block:: dscript - :name: figure_1_2 + :name: figureDIY_1_2 :linenos: - :emphasize-lines: 5,6 + :emphasize-lines: 4,5 Halloween_Treasure_Hunt: type: world - debug: true events: - on player left clicks pumpkin in Hub: + on player left clicks carved_pumpkin in Hub: - narrate "yay" .. rst-class:: figurecaption @@ -100,13 +91,13 @@ Our script should be the following at this point: **Figure 1.2** Our world script with a specific event It's time to *save* the script file, *reload* scripts ingame with ``/denizen reload scripts`` and *trigger the event* -by left clicking a pumpkin block in our Hub world. We should now be able to see a cute little ``yay`` in chat, along -with some debug information in the console, just as we expected. That's great, but we also have to *test* and make -sure the event is not being triggered when clicking other types of blocks, when right clicking, or when clicking in -another world. +by left clicking a carved pumpkin block in our Hub world. We should now be able to see a cute little ``yay`` in chat, +along with some debug information in the console, just as we expected. That's great, but we also have to *test* and +make sure the event is not being triggered when clicking other types of blocks, when right clicking, or when clicking +in another world. -Core Functionality -================== +2. Core Functionality +===================== We're ready to move further ahead and actually give a *reward* to the player clicking the block. Since we're nice server owners, the prize will be a free *diamond*. This is where the :guilabel:`give` command comes in handy. Its @@ -123,29 +114,28 @@ give the diamond to, as the command will target the linked player by default. Th event. The full command line will then be ``- give diamond``. Now it's time to make sure it works. After *saving* and *reloading* scripts again, it should be giving us a *diamond* -every time we click the *pumpkin*. While players will totally love this, we should probably avoid giving out unlimited -diamonds. That's easy to fix though, we just have to *remove* the pumpkin once it's clicked. If we do it before even -giving out the reward, we'll make sure it won't be clicked twice. +every time we click the *carved pumpkin*. While players will totally love this, we should probably avoid giving out +unlimited diamonds. That's easy to fix though, we just have to *remove* the carved pumpkin once it's clicked. If we do +it before even giving out the reward, we'll make sure it won't be clicked twice. For this, we'll use the :guilabel:`modifyblock` command, which lets us specify a *location* and a *material*. Now we only need to know which location was clicked by the player. Time to make use of *context* tags! This kind of tags are event specific and will let us retrieve useful information from said event. If we check again the event's documentation, we can see it has a ```` tag available, which is just what we needed for the first -argument. The material, on the other hand, will be just ``air`` as we want to remove the original pumpkin. The full -command line will then be ``- modifyblock air``. +argument. The material, on the other hand, will be just ``air`` as we want to remove the original carved pumpkin. The +full command line will then be ``- modifyblock air``. Our script with these new commands should look like this: .. code-block:: dscript - :name: figure_1_3 + :name: figureDIY_1_3 :linenos: - :emphasize-lines: 7,8 + :emphasize-lines: 6,7 Halloween_Treasure_Hunt: type: world - debug: true events: - on player left clicks pumpkin in Hub: + on player left clicks carved_pumpkin in Hub: - narrate "yay" - modifyblock air - give diamond @@ -156,20 +146,21 @@ Our script with these new commands should look like this: Rinse and repeat: save, reload scripts and do a quick test. Amazing! This deserves a "yay". Speaking of yays… we don't need to narrate ``yay`` for testing purposes anymore, so we better change it to something more informative. Something -like ``- narrate "You've found a pumpkin! Here's your reward!"`` sounds like the way to go. +like ``- narrate "You've found a carved pumpkin! Here's your reward!"`` sounds like the way to go. -Topping It Off -============== +3. Topping It Off +================= Let's make it even more fun. What if *jack o' lanterns* gave a diamond to *every online player*? Yeah, we can make that happen too! Let's start by making a copy of the event we already have and its contents. We should now change the -``pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack o' lantern blocks. +``carved_pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack o' lantern +blocks. .. note:: - There are other ways to achieve the same result. For example, a single general event that is triggered for every - block clicked could be used. This would mean filtering the needed blocks with logic afterwards, usually with - **if/else if/else** trees or **choose** commands. In this guide though, two separate events will be used as that - can help keep it simple without functionality. + There are other ways to achieve the same result. For example, a single general event that is triggered for both + carved pumpkin and jack o' lantern blocks being clicked could be used. This would mean filtering the needed blocks + with logic afterwards, usually with **if/else if/else** trees or **choose** commands. In this guide though, two + separate events will be used as that can help keep it simple without losing functionality. Inside the event, we need to repeat the give command once per player. How to do that? You've guessed it, a loop! In our case, to wrap the :guilabel:`give` command with a :guilabel:`foreach` loop is all we need. This loop takes a @@ -184,21 +175,20 @@ and we're ready to go. Here's the complete second event: .. code-block:: dscript - :name: figure_1_4 + :name: figureDIY_1_4 :linenos: - :emphasize-lines: 10-14 + :emphasize-lines: 9-13 Halloween_Treasure_Hunt: type: world - debug: true events: - on player left clicks pumpkin in Hub: - - narrate "You've found a pumpkin! Here's your reward!" + on player left clicks carved_pumpkin in Hub: + - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - give diamond on player left clicks jack_o_lantern in Hub: - - narrate "You've found a pumpkin! Here's your reward!" + - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - foreach : - give diamond player: @@ -225,16 +215,16 @@ are shown. No more console *spam*! Finally, this is the full script that we've created: .. code-block:: dscript - :name: figure_1_5 + :name: figureDIY_1_5 :linenos: - :emphasize-lines: 11 + :emphasize-lines: 3,11 Halloween_Treasure_Hunt: type: world debug: false events: - on player left clicks pumpkin in Hub: - - narrate "You've found a pumpkin! Here's your reward!" + on player left clicks carved_pumpkin in Hub: + - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - give diamond From 427a251cf9011a2f625451ca6f4ccde6a70884f5 Mon Sep 17 00:00:00 2001 From: Xenmai Date: Tue, 26 Mar 2019 00:32:56 +0100 Subject: [PATCH 4/6] Keep fixing things --- .../halloween-treasure-hunt.rst | 40 +++++++++---------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst index 396de82..66aa7c1 100644 --- a/source/docs/example-projects/halloween-treasure-hunt.rst +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -16,7 +16,7 @@ In this first example project, we'll start with the basics. The following topics * World script containers, events and context tags. * Common script commands and arguments. * Constructing tags with simple bases and modifiers. -* First contact with foreach loops. +* Basic usage of foreach loops. If you are not familiar with any of the concepts listed, we suggest revisiting the following tutorial documents: @@ -29,30 +29,28 @@ If you are not familiar with any of the concepts listed, we suggest revisiting t This will help you make a better use of this example project, and follow its contents successfully. .. note:: - It is also recommended to have the `meta documentation `_ open in + It is also recommended to have the `meta documentation`__ open in another tab while scripting this project, as we'll need to check the syntax of events, commands and tags very often. +.. __: https://one.denizenscript.com/denizen/logs + 1. First Steps ============== Now let's jump (or slowly crawl) into the scripting process. In our case, we want to make a **Halloween Treasure Hunt** event in our *Hub world*. We plan on manually placing some hidden pumpkins ourselves, and reward players for -finding (and left clicking) them. - -First of all, we'll need to create a *new script file* (for example ``Halloween_Treasure_Hunt.yml``) and build a world -script container which, as we know, will listen to events happening within our server. We just have to give it a name, -like ``Halloween_Treasure_Hunt``, and set the ``type:`` key to ``world``. In addition to this, we'll also add an -``events:`` subkey, which will in the end hold the executable code we're going to write. +finding (and left clicking) them. First of all, we'll need to create a *new script file* (for example +``halloween-treasure-hunt.yml``) and build a world script container which, as we know, will listen to events +happening within our server. Our file with the script container looks like this: .. code-block:: dscript :name: figureDIY_1_1 :linenos: - :emphasize-lines: 1-3 - Halloween_Treasure_Hunt: + halloween_treasure_hunt: type: world events: @@ -61,7 +59,7 @@ Our file with the script container looks like this: **Figure 1.1** Our starting world script container Now we need to find an event that fits our case. Looking through the *event list* documentation, ``on player clicks -block`` looks like our best bet. We just have to adjust it for our specific use case by adding *optional* arguments. +block`` looks like the best match. We just have to adjust it for our specific use case by adding *optional* arguments. According to the event syntax, it accepts a click type, a material and an area, which will just be ``left``, ``carved_pumpkin`` and ``in Hub`` respectively. @@ -80,7 +78,7 @@ Our script should be the following at this point: :linenos: :emphasize-lines: 4,5 - Halloween_Treasure_Hunt: + halloween_treasure_hunt: type: world events: on player left clicks carved_pumpkin in Hub: @@ -132,7 +130,7 @@ Our script with these new commands should look like this: :linenos: :emphasize-lines: 6,7 - Halloween_Treasure_Hunt: + halloween_treasure_hunt: type: world events: on player left clicks carved_pumpkin in Hub: @@ -151,14 +149,14 @@ like ``- narrate "You've found a carved pumpkin! Here's your reward!"`` sounds l 3. Topping It Off ================= -Let's make it even more fun. What if *jack o' lanterns* gave a diamond to *every online player*? Yeah, we can make -that happen too! Let's start by making a copy of the event we already have and its contents. We should now change the -``carved_pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack o' lantern +Let's make it even more fun. What if *jack-o'-lanterns gave a diamond to every online player*? Yeah, we can make that +happen too! Let's start by making a copy of the event we already have and its contents. We should now change the +``carved_pumpkin`` material of said event to ``jack_o_lantern``, so it's only triggered when clicking jack-o'-lantern blocks. .. note:: There are other ways to achieve the same result. For example, a single general event that is triggered for both - carved pumpkin and jack o' lantern blocks being clicked could be used. This would mean filtering the needed blocks + carved pumpkin and jack-o'-lantern blocks being clicked could be used. This would mean filtering the needed blocks with logic afterwards, usually with **if/else if/else** trees or **choose** commands. In this guide though, two separate events will be used as that can help keep it simple without losing functionality. @@ -179,7 +177,7 @@ Here's the complete second event: :linenos: :emphasize-lines: 9-13 - Halloween_Treasure_Hunt: + halloween_treasure_hunt: type: world events: on player left clicks carved_pumpkin in Hub: @@ -207,7 +205,7 @@ problem at all. As we already know, all events related to players let you access Double quotes (``" "``) are used to group text so it's treated as a *single argument*. This is specially useful for commands based on chat text, such as :guilabel:`narrate` and :guilabel:`announce`. -Our command would be as easy as ``- announce " has found a jack o' lantern. Everybody gets a reward!"``. +Our command would be as easy as ``- announce " has found a jack-o'-lantern. Everybody gets a reward!"``. We only have to replace the old narrate command in the second event with our new announce. Now we just have to make sure it *works as intended* after reloading, and finally set the ``debug:`` key to ``false`` so only error messages are shown. No more console *spam*! @@ -219,7 +217,7 @@ Finally, this is the full script that we've created: :linenos: :emphasize-lines: 3,11 - Halloween_Treasure_Hunt: + halloween_treasure_hunt: type: world debug: false events: @@ -229,7 +227,7 @@ Finally, this is the full script that we've created: - give diamond on player left clicks jack_o_lantern in Hub: - - announce " has found a jack o' lantern. Everybody gets a reward!" + - announce " has found a jack-o'-lantern. Everybody gets a reward!" - modifyblock air - foreach : - give diamond player: From 54bb296127ebc8434f5345d16a6e32d459409357 Mon Sep 17 00:00:00 2001 From: Xenmai Date: Tue, 26 Mar 2019 01:07:49 +0100 Subject: [PATCH 5/6] More fixes --- .../halloween-treasure-hunt.rst | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst index 66aa7c1..703bfc2 100644 --- a/source/docs/example-projects/halloween-treasure-hunt.rst +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -29,9 +29,8 @@ If you are not familiar with any of the concepts listed, we suggest revisiting t This will help you make a better use of this example project, and follow its contents successfully. .. note:: - It is also recommended to have the `meta documentation`__ open in - another tab while scripting this project, as we'll need to check the syntax of events, commands and tags very - often. + It is also recommended to have the `meta documentation`__ open in another tab while scripting this project, as + we'll need to check the syntax of events, commands and tags very often. .. __: https://one.denizenscript.com/denizen/logs @@ -58,18 +57,20 @@ Our file with the script container looks like this: **Figure 1.1** Our starting world script container -Now we need to find an event that fits our case. Looking through the *event list* documentation, ``on player clicks -block`` looks like the best match. We just have to adjust it for our specific use case by adding *optional* arguments. +Now we need to find an event that fits our case. Looking through the *event list* documentation, `on player clicks +block`__ looks like the best match. We just have to adjust it for our specific use case by adding *optional* arguments. According to the event syntax, it accepts a click type, a material and an area, which will just be ``left``, ``carved_pumpkin`` and ``in Hub`` respectively. +.. __: https://one.denizenscript.com/denizen/evts/clicks%20block + .. note:: This tutorial assumes our *Hub world* is in fact called ``Hub``. We'll just make sure it works for now, so we add it under the events key and end the line with a ``:``. Inside this event we can place our first command. A good option for testing purposes is just to show a word in *chat*. The command -for this is :guilabel:`narrate`. As the documentation explains, its syntax is very simple, only requiring a message -argument. We feel the hype, so we'll go with a ``- narrate "yay"``. +for this is :guilabel:`narrate`. AIts syntax is very simple, only requiring a message argument. We feel the hype, so +we'll go with a ``- narrate "yay"``. Our script should be the following at this point: @@ -103,25 +104,25 @@ server owners, the prize will be a free *diamond*. This is where the :guilabel:` is a diamond item, so we can ignore the *money* and *xp* options. .. note:: - When reading command documentation, It's important to keep in mind that anything inside ``< >`` is *not literal* - and needs to be replaced. Arguments enclosed in ``[ ]`` are *required*, while ``( )`` means an argument is - *optional*. The ``/`` symbol separates argument *options*, meaning you have to choose one of them. + If you need help with reading the command documentation, refer to this link: `command syntax`__. +.. __: https://one.denizenscript.com/denizen/lngs/syntax". + Let's go ahead and specify ``diamond`` as the first argument of our give command. We don't have to worry about who to give the diamond to, as the command will target the linked player by default. That is, the player that triggered the event. The full command line will then be ``- give diamond``. -Now it's time to make sure it works. After *saving* and *reloading* scripts again, it should be giving us a *diamond* -every time we click the *carved pumpkin*. While players will totally love this, we should probably avoid giving out -unlimited diamonds. That's easy to fix though, we just have to *remove* the carved pumpkin once it's clicked. If we do -it before even giving out the reward, we'll make sure it won't be clicked twice. +Now it's time to make sure it works. After saving and reloading scripts again, it should be giving us a diamond *every +time we click the carved pumpkin*. While players will totally love this, we should probably avoid giving out unlimited +diamonds. That's easy to fix though, we just have to *remove the carved pumpkin once it's clicked*. If we do it before +even giving out the reward, we'll make sure it won't be clicked twice. For this, we'll use the :guilabel:`modifyblock` command, which lets us specify a *location* and a *material*. Now we -only need to know which location was clicked by the player. Time to make use of *context* tags! This kind of tags are -event specific and will let us retrieve useful information from said event. If we check again the event's -documentation, we can see it has a ```` tag available, which is just what we needed for the first -argument. The material, on the other hand, will be just ``air`` as we want to remove the original carved pumpkin. The -full command line will then be ``- modifyblock air``. +only need to know which location was clicked by the player. Time to make use of *context tags*! If you aren't familiar +with them already, you should make sure to revisit the sections where they are covered, **[TODO: Add CONTEXT TAGS section reference]**. +In this case we'll use a simple ```` tag, which is just what we needed for the first argument. The +material, on the other hand, will be just ``air`` as we want to remove the original carved pumpkin. The full command +line will then be ``- modifyblock air``. Our script with these new commands should look like this: @@ -161,14 +162,13 @@ blocks. separate events will be used as that can help keep it simple without losing functionality. Inside the event, we need to repeat the give command once per player. How to do that? You've guessed it, a loop! In -our case, to wrap the :guilabel:`give` command with a :guilabel:`foreach` loop is all we need. This loop takes a -*list* when it starts and executes some commands for *every object* on the list. We just need to feed it the list of -online players, which can be accessed through ````. - -Inside the :guilabel:`foreach` command block, we can retrieve the currently *looped object* with ````. -We'll use this player object to tell the give command who to target. This can easily be done by setting the linked -player of said command, possible thanks to the ``player:`` argument. Feed this argument the tag we've just mentioned -and we're ready to go. +our case, to wrap the :guilabel:`give` command with a :guilabel:`foreach` loop is all we need. We just need to feed it +the list of online players, which can be accessed through ````. + +Ad a reminder, we can retrieve the *currently looped object* inside the :guilabel:`foreach` command block with +````. We'll use this player object to tell the give command who to target. This can easily be done by +setting the linked player of said command, possible thanks to the ``player:`` argument. Feed this argument the tag +we've just mentioned and we're ready to go. Here's the complete second event: From 20884cbfe6271771a321692e3a58024c4ccb414e Mon Sep 17 00:00:00 2001 From: Xenmai Date: Tue, 26 Mar 2019 01:45:13 +0100 Subject: [PATCH 6/6] More Improvements --- .../halloween-treasure-hunt.rst | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/source/docs/example-projects/halloween-treasure-hunt.rst b/source/docs/example-projects/halloween-treasure-hunt.rst index 703bfc2..4d6a4e4 100644 --- a/source/docs/example-projects/halloween-treasure-hunt.rst +++ b/source/docs/example-projects/halloween-treasure-hunt.rst @@ -39,7 +39,7 @@ This will help you make a better use of this example project, and follow its con Now let's jump (or slowly crawl) into the scripting process. In our case, we want to make a **Halloween Treasure Hunt** event in our *Hub world*. We plan on manually placing some hidden pumpkins ourselves, and reward players for -finding (and left clicking) them. First of all, we'll need to create a *new script file* (for example +finding (and left clicking) them. First of all, we'll need to *create a new script file* (for example ``halloween-treasure-hunt.yml``) and build a world script container which, as we know, will listen to events happening within our server. @@ -57,20 +57,20 @@ Our file with the script container looks like this: **Figure 1.1** Our starting world script container -Now we need to find an event that fits our case. Looking through the *event list* documentation, `on player clicks -block`__ looks like the best match. We just have to adjust it for our specific use case by adding *optional* arguments. -According to the event syntax, it accepts a click type, a material and an area, which will just be ``left``, -``carved_pumpkin`` and ``in Hub`` respectively. +Now we need to find an event that fits our case. Looking through the event list documentation, `on player clicks +block`__ looks like the best match. We just have to adjust it for our specific use case by adding optional arguments. +According to the event syntax, it accepts a click type, a material and an area switch, which will just be ``left``, +``carved_pumpkin`` and ``in:Hub`` respectively. .. __: https://one.denizenscript.com/denizen/evts/clicks%20block .. note:: This tutorial assumes our *Hub world* is in fact called ``Hub``. -We'll just make sure it works for now, so we add it under the events key and end the line with a ``:``. Inside this -event we can place our first command. A good option for testing purposes is just to show a word in *chat*. The command -for this is :guilabel:`narrate`. AIts syntax is very simple, only requiring a message argument. We feel the hype, so -we'll go with a ``- narrate "yay"``. +We'll just make sure it works for now, so we add the event to our world script. Inside this event we can place our +first command. A good option for testing purposes is just to show a word in chat, as well as checking out the console +for debug information. The command for this is :guilabel:`narrate`. Its syntax is very simple, only requiring a +message argument. We feel the hype, so we'll go with a ``- narrate "yay"``. Our script should be the following at this point: @@ -82,26 +82,26 @@ Our script should be the following at this point: halloween_treasure_hunt: type: world events: - on player left clicks carved_pumpkin in Hub: + on player left clicks carved_pumpkin in:Hub: - narrate "yay" .. rst-class:: figurecaption **Figure 1.2** Our world script with a specific event -It's time to *save* the script file, *reload* scripts ingame with ``/denizen reload scripts`` and *trigger the event* -by left clicking a carved pumpkin block in our Hub world. We should now be able to see a cute little ``yay`` in chat, -along with some debug information in the console, just as we expected. That's great, but we also have to *test* and -make sure the event is not being triggered when clicking other types of blocks, when right clicking, or when clicking -in another world. +It's time to save the script file, reload scripts ingame with ``/denizen reload scripts`` and trigger the event by +left clicking a carved pumpkin block in our Hub world. We should now be able to see a cute little ``yay`` in chat, +along with some debug information in the console, just as we expected. That's great, but you should also test and make +sure the event is not being triggered when clicking other types of blocks, when right clicking, or when clicking in +another world. 2. Core Functionality ===================== -We're ready to move further ahead and actually give a *reward* to the player clicking the block. Since we're nice -server owners, the prize will be a free *diamond*. This is where the :guilabel:`give` command comes in handy. Its -*syntax* specifies a single required argument: ``[money/xp/|...]``. In our case, what we want to give the player -is a diamond item, so we can ignore the *money* and *xp* options. +We're ready to move further ahead and actually give a reward to the player clicking the block. Since we're nice server +owners, the prize will be a free diamond. This is where the :guilabel:`give` command comes in handy. Its syntax +specifies a single required argument: ``[money/xp/|...]``. In our case, what we want to give the player is a +diamond item, so we can ignore the *money* and *xp* options. .. note:: If you need help with reading the command documentation, refer to this link: `command syntax`__. @@ -119,10 +119,10 @@ even giving out the reward, we'll make sure it won't be clicked twice. For this, we'll use the :guilabel:`modifyblock` command, which lets us specify a *location* and a *material*. Now we only need to know which location was clicked by the player. Time to make use of *context tags*! If you aren't familiar -with them already, you should make sure to revisit the sections where they are covered, **[TODO: Add CONTEXT TAGS section reference]**. -In this case we'll use a simple ```` tag, which is just what we needed for the first argument. The -material, on the other hand, will be just ``air`` as we want to remove the original carved pumpkin. The full command -line will then be ``- modifyblock air``. +with them already, you should make sure to revisit the sections where they are covered, +**[TODO: Add CONTEXT TAGS section reference]**. In this case we'll use a simple ```` tag, which is +just what we needed for the first argument. The material, on the other hand, will be just ``air`` as we want to remove +the original carved pumpkin. The full command line will then be ``- modifyblock air``. Our script with these new commands should look like this: @@ -134,7 +134,7 @@ Our script with these new commands should look like this: halloween_treasure_hunt: type: world events: - on player left clicks carved_pumpkin in Hub: + on player left clicks carved_pumpkin in:Hub: - narrate "yay" - modifyblock air - give diamond @@ -180,12 +180,12 @@ Here's the complete second event: halloween_treasure_hunt: type: world events: - on player left clicks carved_pumpkin in Hub: + on player left clicks carved_pumpkin in:Hub: - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - give diamond - on player left clicks jack_o_lantern in Hub: + on player left clicks jack_o_lantern in:Hub: - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - foreach : @@ -221,12 +221,12 @@ Finally, this is the full script that we've created: type: world debug: false events: - on player left clicks carved_pumpkin in Hub: + on player left clicks carved_pumpkin in:Hub: - narrate "You've found a carved pumpkin! Here's your reward!" - modifyblock air - give diamond - on player left clicks jack_o_lantern in Hub: + on player left clicks jack_o_lantern in:Hub: - announce " has found a jack-o'-lantern. Everybody gets a reward!" - modifyblock air - foreach :