Add Script Injection Example and fix small issue with determine and i…

…njected entries.

src/main/java/net/aufdemrand/denizen/scripts/commands/core/InjectCommand.java

@@ -3,6 +3,7 @@
 import net.aufdemrand.denizen.exceptions.CommandExecutionException;
 import net.aufdemrand.denizen.exceptions.InvalidArgumentsException;
 import net.aufdemrand.denizen.objects.*;
+import net.aufdemrand.denizen.scripts.ScriptBuilder;
 import net.aufdemrand.denizen.scripts.ScriptEntry;
 import net.aufdemrand.denizen.scripts.commands.AbstractCommand;
 import net.aufdemrand.denizen.scripts.queues.ScriptQueue;
@@ -21,6 +22,91 @@
  */
 public class InjectCommand extends AbstractCommand {
 
+    // <--[example]
+    // @Title Script Injection tutorial
+    // @Description
+    // Script injection is an alternative way to run task scripts. Pluses include the ability
+    // to use and modify established definitions and context contained in the script. Check out
+    // this tutorial on some simple ways to use script injection.
+    //
+    // @Code
+    // # +-----------------------------------
+    // # | Script Injection tutorial
+    //
+    // # | Script injection is an alternative way to run task scripts. Pluses include the ability
+    // # | to use and modify established definitions and context contained in the script. Check out
+    // # | this example on some simple ways to use script injection.
+    //
+    // # | Take the example of a 'command pack' script that provides a couple of commands for
+    // # | administrators to use. First, a world script since we need to utilize events.
+    //
+    //
+    // A Cool Command Pack:
+    //   type: world
+    //
+    //   # +-- the SET UP --+
+    //   # Let's create a local script that will check for permissions from players. Since
+    //   # some people using this might want to use different criteria on who should be able to
+    //   # use it (ie. group check/permissions check/op check), it's a good idea to expose this
+    //   # for easy modification. Plus, since it's a utility script, we'll call it with inject
+    //   # to reuse the code in each of the commands provided. We'll call it...
+    //
+    //   command_permission_check:
+    //
+    //   # This just checks op for most basic usage. Add additional comparisons to include more
+    //   # criteria. If the player doesn't meet criteria, clear the queue. Since this code will
+    //   # be injected, it'll clear the queue it was injected to, which in this case is exactly
+    //   # what we need. Clearing the queue will 'cancel' any further execution to the script.
+    //
+    //   # If the player DOES meet criteria, determine the script passively fulfilled. Specifying
+    //   # 'passively' will allow the script to run beyond the 'determination'.
+    //
+    //   - if !<player.is_op> {
+    //       - narrate 'You must be an administrator to use this command!'
+    //       - queue clear
+    //     } else
+    //       - determine passively fulfilled
+    //
+    //
+    //   # +-- the PAYOFF --+
+    //   # Here's a couple simple commands that'll use our injected utility script!
+    //
+    //   events:
+    //
+    //     # | /TEL command - Teleport to your cursor!
+    //     on tel command:
+    //
+    //     # Here's the inject usage, check this out. Since all the commands are intended to be
+    //     # for administrators, making a check here for each command would be counterintutitive.
+    //     # Let's instead just inject the command_permission_check local script! If the conditions
+    //     # aren't met, it'll clear the queue so that the command doesn't go through.
+    //     - inject locally command_permission_check
+    //
+    //     # Now the command, since we've checked permission...
+    //     - narrate 'Teleporting to <player.location.cursor_on.add[0,2,0]>!'
+    //     - teleport location:<player.location.cursor_on[150].add[0,2,0].with_pose[<player>]>
+    //
+    //
+    //     # | /REMOVEMOBS command - Remove vanilla mob entities, not NPCs!
+    //     on removemobs command:
+    //
+    //     # One more example -- notice the code is exactly the same! That's the point! Changing
+    //     # up the command_permission_check local script will change all usages of the script.
+    //     # Utility scripts are cool!
+    //     - inject locally command_permission_check
+    //
+    //     # Now the command, since we've checked permission...
+    //     - narrate 'Removing all mob entities within 15 blocks...!'
+    //     - foreach <player.location.find.entities.within[15]> {
+    //         - if <%value%.is_mob>
+    //           remove %value%
+    //       }
+    //
+    //
+    // # Just remember. 'RUN' makes a NEW queue, and 'INJECT' uses an EXISTING queue!
+    //
+    // -->
+
     @Override
     public void parseArgs(ScriptEntry scriptEntry) throws InvalidArgumentsException {
 
@@ -87,6 +173,8 @@ else if (scriptEntry.hasObject("path"))
             for (ScriptEntry entry : entries)
                     entry.setInstant(true);
 
+        ScriptBuilder.addObjectToEntries(entries, "ReqId", scriptEntry.getObject("ReqId"));
+
         // Inject the entries into the current scriptqueue
         scriptEntry.getResidingQueue().injectEntries(entries, 0);