Add some flag lang meta, fix scenario for flagging invalid npcs/players.

src/main/java/net/aufdemrand/denizen/flags/FlagManager.java

@@ -8,6 +8,96 @@
 
 import java.util.*;
 
+// <--[language]
+// @name flags
+// @description
+// Flags are a feature that is implemented by Denizen to allow the dynamic and persistent storage of information
+// to NPC and Player objects as well as the server on a 'global-scale'. Whether you need to store a quest variable
+// on a player, or you are keeping track of the number of people logging into your server, flags can help.
+//
+// First, a couple facts about flags:
+// 1) They are persistent, that is -- they survive a 'server restart', as long as a '/denizen save' or proper shutdown
+// has been followed.
+// 2) They are stored in flags.yml whenever '/denizen save' is used. Otherwise, since writing to the disk is
+// 'expensive' as far as performance is concerned, they are stored in memory.
+// 3) Flags can be attached to Players, NPCs, or the Server. This means both 'aufdemrand' and 'davidcernat' can have
+// a flag by the same name, but contain separate values if stored to their player-objects.
+// 4) Flags can be booleans, single-item values, or multiple-item arrays, and storing information inside them is
+// smart and reliable.
+// 5) You can set 'expirations' on any flag, allowing a 'maximum' life on a flag. This is great for cooldowns and
+// temporary variables.
+// 6) Flags have world script events, so you can tell when a flag is changing, and react to those changes.
+//
+// Here's the basics:
+//
+// Since the range of information needing to be stored can vary, flags offer a flexible way to handle many situations.
+// Flags in their simplest form are a true/false method of storage, with tags available to check if a flag exists. But
+// they can also store a piece of information, in a 'key/value' relationship. Name the flag, set the value. This can
+// serve a dual purpose, since 1) you can prove it exists, using it as a boolean, and 2) another piece of information
+// can be stored. It's like saying, 'this flag exists, and stored with it is a chunk of information'.
+//
+// The elements stored in flags also have the ability to do perform functions if they are numbers. Easily create
+// a 'counter' with flags, simply by using the 'flag command' to use the '+' feature. Also available is '-' to
+// decrease, '*' to multiply, and '/' to divide the values.
+//
+// Flags can act as arrays of information as well, with the ability to add additional elements to a single flag. Flags
+// with multiple values use a 'smart-index' with the ability to get/remove information via a number, or by its value.
+// Included with the flag command is an easy way to add and remove elements from the array, see the flag command for
+// more information.
+//
+// Flags are modified by using the flag command, and easily read by using a replaceable tag. Here are some examples
+// of some snippets of actual code:
+//
+// Setting a boolean flag to a player, and retrieving it:
+// We'll use the player linked to the script by specifying <player> in the flag command. The next argument
+// is 'stoneskin', shown here without quotes since it's just one word. This will be the name of the flag.
+// Second command, 'narrate', as used below will show the player 'p@player_name has flag 'stoneskin'? true'. The 'true'
+// is retrieved by using the player attribute 'has_flag[flag_name]' to check. If this flag did not exist, it would
+// return false. To see a list of flag tags, see 'A list of flag-specific tags'.
+// <code>
+// - flag <player> stoneskin
+// - narrate "<player> has flag 'stoneskin'? <player.has_flag[stoneskin]>"
+// </code>
+//
+//
+// Using flags as counters:
+// Definitions are nice and light, but sometimes they just don't do the job. For example, using flags in foreach loops
+// is a great idea, and really easy to do.
+// <code>
+//   # initiate a loop for each player that has logged onto the server
+// - foreach <server.list_players> {
+//       # Check if the player's flag 'completed' contains in it an element named 'beginners tutorial'.
+//       # If it does, increment the server flag 'completes_counter' by one, and give it 10 seconds to live.
+//     - if <%value%.flag[completed].as_list> contains 'beginners tutorial'
+//       flag server completes_counter:++ duration:10s
+//   }
+//   # Now show the number of players who had the element in their 'completed' flag.
+// - narrate "The number of players who have completed the beginner's tutorial is<&co> <server.flag[completes_counter]>"
+// </code>
+//
+//
+// Using flags as object storage:
+// Flags can hold fetchable-objects, as well. Let's say players can be friends with NPCs. Why not store the friends
+// on the NPC with a list of player objects?
+// <code>
+// - flag <npc> friends:->:<player>
+// - foreach <npc.flag[friends].as_list> {
+//   chat t:%value% 'You are my friend!'
+// </code>
+//
+// Need to store a location? Store it in a flag!
+// <code>
+// - flag <player> home_location:<player.location.simple>
+// - narrate "Your home location is now '<player.flag[home_location].as_location.formatted>'!"
+// </code>
+//
+//
+// Flags are good for lots of other things too! Check out 'flag command' and 'fl@flag' tags
+// for more specific information.
+
+// -->
+
+
 public class FlagManager {
 
     // Valid flag actions

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

@@ -58,14 +58,14 @@ else if (!scriptEntry.hasObject("flag_target")
             // is being process to make sure the objects don't accidently get set
             // as the name of the flag..
             else if (!scriptEntry.hasObject("flag_target")
-                    && arg.startsWith("n@")) {
+                    && arg.startsWith("n@") && !arg.hasPrefix()) {
                 if (dNPC.valueOf(arg.getValue()) == null)
                     throw new InvalidArgumentsException("Invalid NPC target.");
                 specified_target = true;
                 scriptEntry.addObject("flag_target", arg.asType(dNPC.class));
 
             } else if (!scriptEntry.hasObject("flag_target")
-                    && arg.startsWith("p@")) {
+                    && arg.startsWith("p@") && !arg.hasPrefix()) {
                 if (dPlayer.valueOf(arg.getValue()) == null)
                     throw new InvalidArgumentsException("Invalid Player target.");
                 specified_target = true;