From e55a09f00144674007fd0ff6f121164ea67b9947 Mon Sep 17 00:00:00 2001 From: Jeremy Schroeder Date: Wed, 9 Oct 2013 22:40:54 -0400 Subject: [PATCH] Add some meta for Assignment Scripts and dObjects --- .../aufdemrand/denizen/objects/dMaterial.java | 2 +- .../aufdemrand/denizen/objects/dObject.java | 134 ++++++++++++++++++ .../core/AssignmentScriptContainer.java | 38 +++++ 3 files changed, 173 insertions(+), 1 deletion(-) diff --git a/src/main/java/net/aufdemrand/denizen/objects/dMaterial.java b/src/main/java/net/aufdemrand/denizen/objects/dMaterial.java index 8038b16fe9..8d9fa5e4a9 100644 --- a/src/main/java/net/aufdemrand/denizen/objects/dMaterial.java +++ b/src/main/java/net/aufdemrand/denizen/objects/dMaterial.java @@ -118,7 +118,7 @@ public static enum dMaterials { WHITE_WOOL, ORANGE_WOOL, MAGENTA_WOOL, LIGHT_BLU public final static dMaterial BIRCH_LEAVES = new dMaterial(Material.LEAVES, 2).forceIdentifyAs("BIRCH_LEAVES"); public final static dMaterial JUNGLE_LEAVES = new dMaterial(Material.LEAVES, 3).forceIdentifyAs("JUNGLE_LEAVES"); - // TODO: Need to find a way to handle horizontal logs/etc. Should they be a different material? + // TODO: Need to find a way to handle horizontal logs/etc. Should they be a different dMaterial? public final static dMaterial OAK_LOG = new dMaterial(Material.LOG, 0).forceIdentifyAs("OAK_LOG"); public final static dMaterial SPRUCE_LOG = new dMaterial(Material.LOG, 1).forceIdentifyAs("SPRUCE_LOG"); public final static dMaterial BIRCH_LOG = new dMaterial(Material.LOG, 2).forceIdentifyAs("BIRCH_LOG"); diff --git a/src/main/java/net/aufdemrand/denizen/objects/dObject.java b/src/main/java/net/aufdemrand/denizen/objects/dObject.java index 307915bba3..10d2356484 100644 --- a/src/main/java/net/aufdemrand/denizen/objects/dObject.java +++ b/src/main/java/net/aufdemrand/denizen/objects/dObject.java @@ -2,6 +2,140 @@ import net.aufdemrand.denizen.tags.Attribute; +// <--[language] +// @name dObject +// @description +// dObjects are a system put into place by Denizen that make working with things, or 'objects', +// in Minecraft and Denizen easier. Many parts of scripts will require some kind of object as an +// argument, identifier/type, or such as in world events, part of an event name. The dObjects notation +// system helps both you and Denizen know what type of objects are being referenced and worked with. +// +// So when should you use dObjects? In arguments, event names, replaceable tags, configs, flags, and +// more! If you're just a beginner, you've probably been using them without even realizing it! +// +// dObject is a broader term for a 'type' of object that more specifically represents something, +// such as a dLocation or dScript, often times just referred to as a 'location' or 'script'. Denizen +// employs many object types that you should be familiar with. You'll notice that many times objects +// are reference with their 'dObject notation' which is in the format of 'x@', the x being the specific +// notation of an object type. Example: player objects use the p@ notation, and locations use l@. +// The use of this notation is encouraged, but not always required. +// +// Let's take the tag system, for example. It uses the dObjects system pretty heavily. For instance, +// every time you use or , you're using a dObject, which brings us to a simple +// clarification: Why and not ? That's because Denizen allows Players, +// NPCs and other 'in-context objects' to be linked to certain scripts. In short, already +// contains a reference to a specific player, such as the player that died in a world event 'on player dies'. +// would incorrectly reference the player named 'name', however this format is often +// used to help with usage of a tag, simply indicating 'any player object'. +// +// dObjects can be used to CREATE new instances of objects, too! Though not all types allow 'new' +// objects to be created, many do, such as dItems. With the use of tags, it's easy to reference a specific +// item, say -- an item in the Player's hand -- items are also able to use a constructor to make a new item, +// and say, drop it in the world. Take the case of the command/usage '- drop i@diamond_ore'. The item object +// used is a brand new diamond_ore, which is then dropped by the command to a location of your choice -- just +// specify an additional location argument. +// +// There's a great deal more to learn about dObjects, so be sure to check out each object type for more +// specific information. While all dObjects share some features, many contain goodies on top of that! +// +// Here's an overview of each object type that is implemented by the Denizen core: +// +// + ----- dPlayer ----- + +// | object notation: p@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | p@ - fetches an online or offline player with 'player_name' +// +// + ----- dNPC ---------+ +// | object notation: n@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | n@ - fetches the NPC with the specified id +// | n@ - fetches the first NPC found with the specified name +// +// + ----- dLocation ----+ +// | object notation: l@ can reference unique objects: no can be notable: yes +// | constructors: ( <>'s represent non-static information and are not literal) +// | l@,,, - fetches a specific location +// | l@ - fetches the location that has been 'noted' with the specified id +// +// + ----- dEntity ------+ +// | object notation: e@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | e@ - fetches a new entity with the specified type as implemented by bukkit's entity type enumeration +// | e@ - fetches a new custom entity as specified by the referenced entity script (soon) +// | e@ - fetches the entity that has the (temporary) entity id set by bukkit +// | e@random - fetches a new, random entity +// +// + ----- dItem --------+ +// | object notation: i@ can reference unique objects: no can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | i@ - fetches a new item of the specified material +// | i@, - fetches a new item with the specified data +// | i@ - fetches an item that is laying on the ground in a world by its bukkit entity_id +// | i@ - fetches a new custom item as specified by the referenced item script +// +// + ----- dWorld -------+ +// | object notation: w@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | w@ - fetches the world with the specified name +// +// + ----- dColor -------+ +// | object notation: c@ can reference unique objects: no can be notable: soon +// | constructors: ( <>'s represent non-static information and are not literal) +// | c@ - fetches a named color, as implemented by bukkit's color enumeration +// | c@,, - fetches a color make of the specified r,g,b values +// | c@random - fetches a random color +// +// + ----- dCuboid ------+ +// | object notation: cu@ can reference unique objects: no can be notable: yes +// | constructors: ( <>'s represent non-static information and are not literal) +// | cu@| - fetches a new cuboid with the specified locations as 'pos1' and 'pos2' +// | cu@ - fetches the cuboid that has been 'noted' with the specified id +// +// + ----- dInventory ---+ +// | object notation: in@ can reference unique objects: yes can be notable: soon +// | constructors: ( <>'s represent non-static information and are not literal) +// | in@player[] - fetches the specified Player's inventory +// | in@npc[] - fetches the specified NPC's inventory +// | in@entity[] - fetches the specified object's inventory, such as a Player, NPC, or Mule +// | in@location[] - fetches the contents of a chest or other 'inventory' block +// | in@ - fetches the inventory that has been 'noted' with the specified id +// | in@ - fetches a new custom inventory as specified by the referenced inventory script +// +// + ----- dMaterial ----+ +// | object notation: m@ can reference unique objects: no can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | m@ - fetches the material as specified by bukkit's material enumeration +// | m@, - fetches the material as specified by bukkit's material enumeration with specified data +// | m@ - fetches the material specified by Denizen's 'data variety' dMaterials +// | m@random - fetches a random material +// +// + ----- dList -------+ +// | object notation: li@,fl@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | li@ - fetches a new list with the elements specified, seperated by a pipe (|) character +// | li@val[] - slightly more verbose, but tag friendly way to fetch a new list (allows periods) +// | fl@ - fetches the flag list value of the specified server flag, as a dList +// | fl[ - fetches the flag list value of the specified player/npc's flag, as a dList +// +// + ----- dScript -------+ +// | object notation: s@ can reference unique objects: yes can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | w@ - fetches the script container with the specified name +// +// + ----- Duration ------+ +// | object notation: d@ can reference unique objects: no can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | d@ - fetches a duration object with the specified amount of time +// | d@| - fetches a duration that is randomly selected between the specified 'low' and 'high' +// +// + ----- Element ------+ +// | object notation: el@ can reference unique objects: no can be notable: no +// | constructors: ( <>'s represent non-static information and are not literal) +// | el@ - fetches an element with the specified value +// | el@val[] - slightly more verbose, but tag friendly way to fetch a new element (allows periods) +// +// --> + public interface dObject { /** diff --git a/src/main/java/net/aufdemrand/denizen/scripts/containers/core/AssignmentScriptContainer.java b/src/main/java/net/aufdemrand/denizen/scripts/containers/core/AssignmentScriptContainer.java index 5a0ec6d934..1d150e9b21 100644 --- a/src/main/java/net/aufdemrand/denizen/scripts/containers/core/AssignmentScriptContainer.java +++ b/src/main/java/net/aufdemrand/denizen/scripts/containers/core/AssignmentScriptContainer.java @@ -3,6 +3,44 @@ import net.aufdemrand.denizen.scripts.containers.ScriptContainer; import org.bukkit.configuration.ConfigurationSection; +// <--[language] +// @name Assignment Script-Containers +// @description +// Assignment script-containers provide functionality to NPCs by 'assignment' of the container. Assignment +// scripts are meant to be used when customizing the normal behavior of NPCs. This can be used on a 'per-npc' basis, +// but the encouraged approach is to design assignment scripts in a way that they can be used for multiple NPCs, +// perhaps with the use of constants or flags to determine specific information required by the scripts. + +// Features unique to assignment script-containers include 'actions', 'constants', and 'interact script' assignment. +// Like any script, the ability to run local utility scripts can be accomplished as well. This allows fully +// interactive NPCs to be built purely with Assignment Scripts, and for advanced situations, world scripts and +// interact scripts can provide more functionailty. + +// Basic structure of an assignment script: +// +// Assignment script container name: +// type: assignment +// +// actions: +// on : +// - ... +// +// constants: +// : +// : +// - ... +// +// interact scripts: +// - +// - ... +// +// +// +// Unlike other script containers, all part of an assignment script are optional. The three features provided can be +// used together, but do not require one another. + +// --> + public class AssignmentScriptContainer extends ScriptContainer { public AssignmentScriptContainer(ConfigurationSection configurationSection, String scriptContainerName) {