Denizen/0.7/Interact Scripts: Difference between revisions

From Citizens Wiki

< Denizen‎ | 0.7

No edit summary
 
(27 intermediate revisions by 4 users not shown)
Line 1: Line 1:
For more up-to-date information and full details on specific features (individual commands or tags, for example), check the [https://one.denizenscript.com/denizen/cmds/ Meta Documentation].
If you want a full tutorial to help get you set up, check out the [https://one.denizenscript.com/denizen/cmds/denizen/vids Tutorial Videos] on youtube or the [https://guide.denizenscript.com/ Beginner's Guide] text website.
If you need quick help, visit our [https://discord.gg/Q6pZGSR Discord group].
<br><br><br>
<span style="font-family:natalya-alternate-one; font-size:300%; margin-right:-7px; margin-left:-10px;">This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!</span>
<s>
== Interact Scripts ==
== Interact Scripts ==
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Hopefully you've gotten a basic idea of a script by reading about Assignments in the previous section. If you have, you'll notice that the general structure of a script should always include the 'Name', 'Type', 'Requirements', and 'Steps' nodes.


Scripts are defined in the plugins/Denizen/scripts/ folder. Any .yml file in that directory will be loaded into Denizen. For example purposes on this website, reference to script.yml is made, but again, jimbobjoe.yml or 'skeeter the cat.yml' would work just the same..
Scripts are defined in the plugins/Denizen/scripts/ folder. Any .yml file in that directory will be loaded into Denizen. For example purposes on this website, reference to script.yml is made, but again, jimbobjoe.yml or 'skeeter the cat.yml' would work just the same..
</div>
</div>


==== General layout of an Interact Script ====
==== General layout of an Interact Script ====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
This small 'outline' below shows the general layout of an Interact Script. Remember: SPACING is INCREDIBLY important with YML. If you are receiving a <code>SnakeYML</code> error in your console when working with any YML file, 99% of the time it is because of bad spacing or a missing ':' colon. YAML tutorials can be intimidating, but [http://ess.khhq.net/wiki/YAML_Tutorial this small tutorial] on the Essentials wiki is pretty useful for basic YAML, which is the extent of which Denizens uses.
<pre>
<pre>
'Name of script':  # Name Node
'Name of script':  # Name Node
   Type: Interact    # Type Node
   Type: Interact    # Type Node
   Requirements:    # Requirements Node
   Requirements:    # Requirements Node
     ...:
     Mode: ...
     ...:
     List:  
      - ...
    - ...
      - ...
    - ...
   Steps:            # Steps Node
   Steps:            # Steps Node
     ...:
  1:              # Step Node
       - ...
    Some Trigger:  # Trigger Node
    ...:
      Trigger: ...
      Script:     # Script Node
        - ...
        - ...
    Another Trigger:
       Script:
        - ...
        - ...
</pre>
</pre>
For information on what goes in Requirements and Steps, keep reading. What is show above is just a an outline of the correct spacing, not a valid script! Let's take a look at a few small scripts, below.
</div>
</div>
==== A few small scripts ====
...just to get a small look of some basic ways to use scripts. The rest of this document will go into detail about the specifics of each part. Some of the functionality described may require additional reading.
This scripts below is a neat little way to leave a hint. Upon a Player coming into proximity, this script will trigger the NPC looking at a target while holding a small conversation with the player.
<pre>
"A Hint in the Sky":
  Type: Interact 
  Requirements:
    Mode: None
  Steps:
    1:
      Proximity Trigger:
        Script:
        - ^COOLDOWN 15
        - LOOK CLOSE
        - ^CHAT "Look up there! What could that possibly be used for?"
        - LOOK BOOKMARK:upthere DURATION:10
        - WAIT 1
        - CHAT "If only I could figure out how to make it, I can't find any stairs!"
</pre>
Below is a script for a nice fellow who will help an adventurer out in the night-time. Keep in mind that Interact Scripts only define one set of rules for a Denizen NPC... player-interaction. Imagine this next script combined with some activities that make the Denizen NPC scope out and wander an area in some woods.
<pre>
"Night-time Helper":
  Type: Interact
  Requirements:
    Mode: All
    List:
    - TIME NIGHT
  Steps:
    1:
      Click Trigger:
        Script:
        - ^ZAP DURATION:60
        - ENGAGE DURATION: 5
        - LOOK CLOSE DURATION:5
        - CHAT "It's dark out here, man!"
        - CHAT "You really gotta watch out for those Zombies... they're all over the place!"
    2:
      Click Trigger:
        Script:
        - ^COOLDOWN 3600
        - LOOK CLOSE DURATION:5
        - CHAT "You again, eh? Hey man.. you need some torches?"
        - WAIT 1
        - GIVE TORCH QTY:12
</pre>
Scripts can also start a story-line of adventures, all activated by scripts working together, thanks to the FLAG, FAIL, and FINISH commands. This small script below could be the start of a Quest, with two different outcomes, if utilized properly.


==== Name Node ====
==== Name Node ====
Line 30: Line 108:
* If the name includes a single quote in it, you must use double quotes around it, or 'escape' the quote with another quote. ie: <code>"John's Script":</code> or <code>'John<nowiki>''</nowiki>s Script':</code>
* If the name includes a single quote in it, you must use double quotes around it, or 'escape' the quote with another quote. ie: <code>"John's Script":</code> or <code>'John<nowiki>''</nowiki>s Script':</code>
</div>
</div>


==== Type Node ====
==== Type Node ====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Let's Denizen know the type of script. For interact scripts, as explained in this section, use <code>TYPE: INTERACT</code>. For reference, there are also TASK scripts and ACTIVITY scripts, which is covered later.
Let's Denizen and you to easily know the type of script. For interact scripts, as explained in this section, use <code>TYPE: INTERACT</code>. For reference, there are also TASK scripts and ACTIVITY scripts, which are covered in their appropriate sections.
</div>
</div>


==== Requirements Node ====
==== Requirements Node ====
Line 51: Line 131:
This would be a difficult script to obtain, for sure. To trigger, the time must be night-time, the player would need one million units of currency, and the weather must be storming, but it shows the flexibility of requirements. First is the 'Mode'. Currently there are three different types. Second is the requirement type, with arguments if applicable.
This would be a difficult script to obtain, for sure. To trigger, the time must be night-time, the player would need one million units of currency, and the weather must be storming, but it shows the flexibility of requirements. First is the 'Mode'. Currently there are three different types. Second is the requirement type, with arguments if applicable.
</code>
</code>


===== Requirements Mode =====
===== Requirements Mode =====
Line 56: Line 137:
<code>[] indicates required field.</code>
<code>[] indicates required field.</code>


{{Denizen Requiremnt Type Color |white|
{{Denizen Requirement Type Color |white|
ALL
ALL
| &nbsp;&nbsp;Requires all requirements listed to be met.
| &nbsp;&nbsp;Requires all requirements listed to be met.
}}
}}
{{Denizen Requiremnt Type Color |white|
{{Denizen Requirement Type Color |white|
ANY [#]
ANY #
| &nbsp;&nbsp;Requires the specified number of requirements to be met out of the total of requirements.
| &nbsp;&nbsp;Requires the specified number of requirements to be met out of the total of requirements.
}}
}}
{{Denizen Requiremnt Type Color |white|
{{Denizen Requirement Type Color |white|
NONE
NONE
| &nbsp;&nbsp;No requirements need to be met. There is also no need to have a <tt>LIST</tt> node if using <tt>NONE</tt>.
| &nbsp;&nbsp;No requirements need to be met. There is also no need to have a <tt>LIST</tt> node if using <tt>NONE</tt>.
Line 70: Line 151:
</div>
</div>


===== Requirements =====
=====Requirements=====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
For a complete list of Interact Requirements, and information on those requirements,
Denizen has a large assortment of Requirements at your disposal. For a complete list, and information on those requirements,
See: [[Denizen/Interact Scripts/Interact Requirements]]
see: [[Denizen/0.7/Interact Scripts/Interact Requirements]]


Remember, requirements are also easily extensible by plugin programmers, or maybe even you!
Remember, requirements are also easily extensible by plugin programmers, or maybe even you!<br>
See: [[Denizen/Interact Scripts/Custom Interact Requirements]]
See: [[Denizen/0.7/Interact Scripts/Custom Interact Requirements]]


</div>
</div>
Line 83: Line 164:
==== Steps Node ====
==== Steps Node ====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Steps are the meat of the script. They control what to listen for and what actions to take. Each script can have multiple steps, each with multiple triggers. Let's use an example.
Each script can have multiple steps, each with multiple triggers. A player can only ever be on 1 step for a script. When a script is selected to run, a query is made to the Denizen saves to see if the Player has completed any steps. If no entry is found, the player starts on Step 1.
 
Here's an example of s script making good use of steps. Note the ZAP command is what moves a player from one step to the next, it is NOT automatic!


<pre>
<pre>
Line 94: Line 177:
       Click Trigger:
       Click Trigger:
         Script:
         Script:
         - CHAT 'What's your name, stranger?'
         - CHAT "What's your name, stranger?"
       Chat Trigger:
       Chat Trigger:
         '1':
         '1':
           Trigger: My name is /<PLAYER>/.
           Trigger: My name is /<PLAYER>/.
           Script:
           Script:
           - CHAT 'Ah ha, your name sounds familiar! '
           - CHAT "Ah ha, your name sounds familiar!"
           - CHAT 'Are you from around this area?'
           - CHAT "Are you from around this area?"
           - ZAP
           - ZAP
     '2':
     '2':
Line 110: Line 193:
           Trigger: /Yes/, I grew up in Harbortown!
           Trigger: /Yes/, I grew up in Harbortown!
           Script:
           Script:
           - CHAT 'I thought so, welcome back!  
           - CHAT "I thought so, welcome back!  
             Have you heard about Tom the Taylor?  
             Have you heard about Tom the Taylor?  
             Isn't that just horrible?'
             Isn't that just horrible?"
           - ZAP 3  
           - ZAP 3  
         '2':
         '2':
           Trigger: /No/, you must be mistaken.  
           Trigger: /No/, you must be mistaken.  
           Script:
           Script:
           - CHAT 'Oh, sorry about that.'
           - CHAT "Oh, sorry about that."
           - CHAT 'Hey, if you're looking for some work,  
           - CHAT "Hey, if you're looking for some work,  
             Bill the Baker is understaffed!  
             Bill the Baker is understaffed!  
             This is the bakery's busy season.'
             This is the bakery's busy season."
           - ZAP 4
           - ZAP 4
     '3':
     '3':
       Click Trigger:
       Click Trigger:
         Script:
         Script:
         - CHAT 'I wonder if Tom the Taylor is doing any better.'
         - CHAT "I wonder if Tom the Taylor is doing any better."
         - NARRATE 'Perhaps you should check on Tom the Taylor.'
         - NARRATE "Perhaps you should check on Tom the Taylor."
     '4':
     '4':
       Click Trigger:
       Click Trigger:
         Script:
         Script:
         - CHAT 'Oh, nice to see you again <PLAYER>!'
         - CHAT "Oh, nice to see you again <PLAYER>!"
         - CHAT 'Have you stopped by the bakery?'
         - CHAT "Have you stopped by the bakery?"
</pre>
</pre>


The sub-sections below reference this example.
</div>
</div>


====Trigger Nodes====
*For a list of the available Triggers see [[Denizen/0.7/Interact_Scripts/Triggers|Triggers]]
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
*For a list of the available Commands see [[Denizen/0.7/Interact_Scripts/Commands|Commands]]
Steps handle the flow of commands and messages with triggers.
 
'''Denizen Triggers''' trigger from interaction with Denizens. They are defined in the Steps: node.
 
* '''Click Trigger'''s activate when the Denizen is right-clicked.
<pre>
Click Trigger:
  Script:
  - CHAT "Teehee, that tickles!"
  - EMOTE "giggles"
</pre>
 
* '''Damage Trigger'''s activate when the Denizen is left-clicked. If the Denizen has Damage Triggers disabled, this will count as a Click Trigger.
<pre>
Damage Trigger:
  Script:
  - CHAT "OUCH, You'll pay for that!"
  - STRIKE <PLAYER>
</pre>


* '''Proximity Trigger'''s activate when a player walks close to the Denizen.
==Assigning==
See [[Denizen/0.7/Assignments#Interact_Assignment]]


<pre>
Proximity Trigger:
  Script:
  - CHAT 'Eek! get away, you smell bad, <PLAYER>.'
</pre>




* '''Chat Trigger'''s activate when players chat with Denizens. Players' chat within the configurable range will be directed to the Denizen instead of global chat. Chat also follows the configuration setting. a single chat trigger entry can handle multiple words, see below:
</div>
 
<pre>
Chat Trigger:
  '1':
    Trigger: The word needed to /Trigger/ is inside slashes, this whole sentence will appear to be said by the player
    Script:
    - CHAT "Good to know!"
  '2':
    Trigger: A chat trigger can also catch on any word not otherwise caught using /*/.
    Script:
    - CHAT "I don't know what <*> mean, <PLAYER>!"
</pre>
 
* '''Location Trigger'''s activate when players walk near a [[Location Bookmark]]. Like chat triggers, multiple locations can be defined in one Location Trigger. They are similar in format to Chat Triggers in the fact that there can be multiple triggers per step.


<pre>
[[Category:Denizen 0.7]]</s>
Location Trigger:
  '1':
    Trigger: TreasureRoom
    - TELEPORT BOOKMARK:Jail
  '2':
    Trigger: BedRoom
    - NARRATE 'You enter the bedroom of the dead man, looking for clues'
</pre>
 
For a full list of commands, see [[#Script Commands]]
</div>

Latest revision as of 16:11, 24 March 2020

For more up-to-date information and full details on specific features (individual commands or tags, for example), check the Meta Documentation.

If you want a full tutorial to help get you set up, check out the Tutorial Videos on youtube or the Beginner's Guide text website.

If you need quick help, visit our Discord group.




This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!


Interact Scripts

Scripts are defined in the plugins/Denizen/scripts/ folder. Any .yml file in that directory will be loaded into Denizen. For example purposes on this website, reference to script.yml is made, but again, jimbobjoe.yml or 'skeeter the cat.yml' would work just the same..


General layout of an Interact Script

This small 'outline' below shows the general layout of an Interact Script. Remember: SPACING is INCREDIBLY important with YML. If you are receiving a SnakeYML error in your console when working with any YML file, 99% of the time it is because of bad spacing or a missing ':' colon. YAML tutorials can be intimidating, but this small tutorial on the Essentials wiki is pretty useful for basic YAML, which is the extent of which Denizens uses.

'Name of script':   # Name Node
  Type: Interact    # Type Node
  Requirements:     # Requirements Node
    Mode: ...
    List: 
    - ...
    - ...
  Steps:            # Steps Node
   1:               # Step Node
    Some Trigger:   # Trigger Node
      Trigger: ...
      Script:     # Script Node
        - ...
        - ...
     Another Trigger:
      Script:
        - ...
        - ...

For information on what goes in Requirements and Steps, keep reading. What is show above is just a an outline of the correct spacing, not a valid script! Let's take a look at a few small scripts, below.

A few small scripts

...just to get a small look of some basic ways to use scripts. The rest of this document will go into detail about the specifics of each part. Some of the functionality described may require additional reading.

This scripts below is a neat little way to leave a hint. Upon a Player coming into proximity, this script will trigger the NPC looking at a target while holding a small conversation with the player.

"A Hint in the Sky":
  Type: Interact   
  Requirements:
    Mode: None
  Steps:
    1:
      Proximity Trigger:
        Script:
        - ^COOLDOWN 15
        - LOOK CLOSE
        - ^CHAT "Look up there! What could that possibly be used for?"
        - LOOK BOOKMARK:upthere DURATION:10
        - WAIT 1
        - CHAT "If only I could figure out how to make it, I can't find any stairs!"


Below is a script for a nice fellow who will help an adventurer out in the night-time. Keep in mind that Interact Scripts only define one set of rules for a Denizen NPC... player-interaction. Imagine this next script combined with some activities that make the Denizen NPC scope out and wander an area in some woods.

"Night-time Helper":
  Type: Interact
  Requirements:
    Mode: All
    List:
    - TIME NIGHT
  Steps:
    1:
      Click Trigger:
        Script:
        - ^ZAP DURATION:60
        - ENGAGE DURATION: 5
        - LOOK CLOSE DURATION:5
        - CHAT "It's dark out here, man!"
        - CHAT "You really gotta watch out for those Zombies... they're all over the place!"
    2:
      Click Trigger:
        Script:
        - ^COOLDOWN 3600
        - LOOK CLOSE DURATION:5
        - CHAT "You again, eh? Hey man.. you need some torches?"
        - WAIT 1
        - GIVE TORCH QTY:12


Scripts can also start a story-line of adventures, all activated by scripts working together, thanks to the FLAG, FAIL, and FINISH commands. This small script below could be the start of a Quest, with two different outcomes, if utilized properly.

Name Node

This node is pretty self-explanatory, but here are some things to keep in mind.

  • Names, just like nodes are case-sensitive! 'This script name' is different than 'THIS SCRIPT NAME'.
  • Names that contain spaces should have single or double quotes around it. ie: "This script": or 'This script': is acceptable.
  • If the name includes a single quote in it, you must use double quotes around it, or 'escape' the quote with another quote. ie: "John's Script": or 'John''s Script':


Type Node

Let's Denizen and you to easily know the type of script. For interact scripts, as explained in this section, use TYPE: INTERACT. For reference, there are also TASK scripts and ACTIVITY scripts, which are covered in their appropriate sections.


Requirements Node

This node sets the rules for the player to qualify for the script. There are a couple different options that you should know when using requirements. For example:

 Requirements:
   Mode: All
   List:
   - TIME Night
   - MONEY 1000000
   - STORMY

This would be a difficult script to obtain, for sure. To trigger, the time must be night-time, the player would need one million units of currency, and the weather must be storming, but it shows the flexibility of requirements. First is the 'Mode'. Currently there are three different types. Second is the requirement type, with arguments if applicable.


Requirements Mode

[] indicates required field.

ALL

  Requires all requirements listed to be met.

ANY #

  Requires the specified number of requirements to be met out of the total of requirements.

NONE

  No requirements need to be met. There is also no need to have a LIST node if using NONE.
Requirements

Denizen has a large assortment of Requirements at your disposal. For a complete list, and information on those requirements, see: Denizen/0.7/Interact Scripts/Interact Requirements

Remember, requirements are also easily extensible by plugin programmers, or maybe even you!
See: Denizen/0.7/Interact Scripts/Custom Interact Requirements


Steps Node

Each script can have multiple steps, each with multiple triggers. A player can only ever be on 1 step for a script. When a script is selected to run, a query is made to the Denizen saves to see if the Player has completed any steps. If no entry is found, the player starts on Step 1.

Here's an example of s script making good use of steps. Note the ZAP command is what moves a player from one step to the next, it is NOT automatic!

'Welcome to Harbortown':
  Type: Interact
  Requirements:
    Mode: NONE
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT "What's your name, stranger?"
      Chat Trigger:
        '1':
          Trigger: My name is /<PLAYER>/.
          Script:
          - CHAT "Ah ha, your name sounds familiar!"
          - CHAT "Are you from around this area?"
          - ZAP
    '2':
      Click Trigger:
        Script:
        - HINT
      Chat Trigger:
        '1':
          Trigger: /Yes/, I grew up in Harbortown!
          Script:
          - CHAT "I thought so, welcome back! 
            Have you heard about Tom the Taylor? 
            Isn't that just horrible?"
          - ZAP 3 
        '2':
          Trigger: /No/, you must be mistaken. 
          Script:
          - CHAT "Oh, sorry about that." 
          - CHAT "Hey, if you're looking for some work, 
            Bill the Baker is understaffed! 
            This is the bakery's busy season."
          - ZAP 4
    '3':
      Click Trigger:
        Script:
        - CHAT "I wonder if Tom the Taylor is doing any better."
        - NARRATE "Perhaps you should check on Tom the Taylor."
    '4':
      Click Trigger:
        Script:
        - CHAT "Oh, nice to see you again <PLAYER>!"
        - CHAT "Have you stopped by the bakery?"
  • For a list of the available Triggers see Triggers
  • For a list of the available Commands see Commands

Assigning

See Denizen/0.7/Assignments#Interact_Assignment