From 8cfbd26f6b7fc9f47bb31f09692c6283537780fc Mon Sep 17 00:00:00 2001 From: Justin Aquadro Date: Tue, 28 Jun 2011 03:41:44 +0000 Subject: [PATCH] Documentation, tweaking (get used to this...) --- Substrate/SubstrateCS/Source/Chunk.cs | 2 +- .../SubstrateCS/Source/NBT/INBTObject.cs | 2 - .../Source/TileEntities/TileEntityChest.cs | 2 +- .../Source/TileEntities/TileEntityFurnace.cs | 2 +- .../TileEntities/TileEntityMobSpawner.cs | 2 +- .../Source/TileEntities/TileEntityMusic.cs | 2 +- .../TileEntities/TileEntityRecordPlayer.cs | 2 +- .../Source/TileEntities/TileEntitySign.cs | 2 +- .../Source/TileEntities/TileEntityTrap.cs | 2 +- Substrate/SubstrateCS/Source/TileEntity.cs | 70 +++++++++++++++++-- .../SubstrateCS/Source/TileEntityFactory.cs | 27 ++++++- 11 files changed, 100 insertions(+), 15 deletions(-) diff --git a/Substrate/SubstrateCS/Source/Chunk.cs b/Substrate/SubstrateCS/Source/Chunk.cs index aba1fdb..740261b 100644 --- a/Substrate/SubstrateCS/Source/Chunk.cs +++ b/Substrate/SubstrateCS/Source/Chunk.cs @@ -32,7 +32,7 @@ namespace Substrate new SchemaNodeArray("BlockLight", 16384), new SchemaNodeArray("HeightMap", 256), new SchemaNodeList("Entities", TagType.TAG_COMPOUND, 0, SchemaOptions.CREATE_ON_MISSING), - new SchemaNodeList("TileEntities", TagType.TAG_COMPOUND, TileEntity.BaseSchema, SchemaOptions.CREATE_ON_MISSING), + new SchemaNodeList("TileEntities", TagType.TAG_COMPOUND, TileEntity.Schema, SchemaOptions.CREATE_ON_MISSING), new SchemaNodeScaler("LastUpdate", TagType.TAG_LONG, SchemaOptions.CREATE_ON_MISSING), new SchemaNodeScaler("xPos", TagType.TAG_INT), new SchemaNodeScaler("zPos", TagType.TAG_INT), diff --git a/Substrate/SubstrateCS/Source/NBT/INBTObject.cs b/Substrate/SubstrateCS/Source/NBT/INBTObject.cs index 57e8817..624d68b 100644 --- a/Substrate/SubstrateCS/Source/NBT/INBTObject.cs +++ b/Substrate/SubstrateCS/Source/NBT/INBTObject.cs @@ -1,6 +1,4 @@ using System; -using System.Collections.Generic; -using System.Text; namespace Substrate.NBT { diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityChest.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityChest.cs index fc7a515..073946d 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityChest.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityChest.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityChest : TileEntity, IItemContainer { - public static readonly SchemaNodeCompound ChestSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound ChestSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "Chest"), new SchemaNodeList("Items", TagType.TAG_COMPOUND, ItemCollection.InventorySchema), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityFurnace.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityFurnace.cs index 57e4770..00d48f4 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityFurnace.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityFurnace.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityFurnace : TileEntity, IItemContainer { - public static readonly SchemaNodeCompound FurnaceSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound FurnaceSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "Furnace"), new SchemaNodeScaler("BurnTime", TagType.TAG_SHORT), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityMobSpawner.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityMobSpawner.cs index b83b607..f7098e9 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityMobSpawner.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityMobSpawner.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityMobSpawner : TileEntity { - public static readonly SchemaNodeCompound MobSpawnerSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound MobSpawnerSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "MobSpawner"), new SchemaNodeScaler("EntityId", TagType.TAG_STRING), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityMusic.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityMusic.cs index 5a0aca1..2262215 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityMusic.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityMusic.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityMusic : TileEntity { - public static readonly SchemaNodeCompound MusicSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound MusicSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "Music"), new SchemaNodeScaler("note", TagType.TAG_BYTE), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityRecordPlayer.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityRecordPlayer.cs index 2874168..3a8cbbe 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityRecordPlayer.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityRecordPlayer.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityRecordPlayer : TileEntity { - public static readonly SchemaNodeCompound RecordPlayerSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound RecordPlayerSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "RecordPlayer"), new SchemaNodeScaler("Record", TagType.TAG_INT, SchemaOptions.OPTIONAL), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntitySign.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntitySign.cs index 3f00f9b..e7a61ef 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntitySign.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntitySign.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntitySign : TileEntity { - public static readonly SchemaNodeCompound SignSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound SignSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "Sign"), new SchemaNodeScaler("Text1", TagType.TAG_STRING), diff --git a/Substrate/SubstrateCS/Source/TileEntities/TileEntityTrap.cs b/Substrate/SubstrateCS/Source/TileEntities/TileEntityTrap.cs index cb691b3..ca5a44c 100644 --- a/Substrate/SubstrateCS/Source/TileEntities/TileEntityTrap.cs +++ b/Substrate/SubstrateCS/Source/TileEntities/TileEntityTrap.cs @@ -8,7 +8,7 @@ namespace Substrate.TileEntities public class TileEntityTrap : TileEntity, IItemContainer { - public static readonly SchemaNodeCompound TrapSchema = BaseSchema.MergeInto(new SchemaNodeCompound("") + public static readonly SchemaNodeCompound TrapSchema = TileEntity.Schema.MergeInto(new SchemaNodeCompound("") { new SchemaNodeString("id", "Trap"), new SchemaNodeList("Items", TagType.TAG_COMPOUND, ItemCollection.InventorySchema), diff --git a/Substrate/SubstrateCS/Source/TileEntity.cs b/Substrate/SubstrateCS/Source/TileEntity.cs index 132af13..89fe5ca 100644 --- a/Substrate/SubstrateCS/Source/TileEntity.cs +++ b/Substrate/SubstrateCS/Source/TileEntity.cs @@ -1,15 +1,19 @@ using System; -using System.Collections.Generic; -using System.Text; namespace Substrate { using NBT; using Utility; + /// + /// Represents a Tile Entity record, which provides additional data to a block. + /// + /// Generally, this class should be subtyped into new concrete Tile Entity types, as this generic type is unable to + /// capture any of the custom data fields that make Tile Entities useful in the first place. It is however still possible to + /// create instances of objects, which may allow for graceful handling of unknown Tile Entities. public class TileEntity : INBTObject, ICopyable { - public static readonly SchemaNodeCompound BaseSchema = new SchemaNodeCompound("") + private static readonly SchemaNodeCompound _schema = new SchemaNodeCompound("") { new SchemaNodeScaler("id", TagType.TAG_STRING), new SchemaNodeScaler("x", TagType.TAG_INT), @@ -22,34 +26,54 @@ namespace Substrate private int _y; private int _z; + /// + /// Gets the id (name) of the Tile Entity. + /// public string ID { get { return _id; } } + /// + /// Gets or sets the global X-coordinate of the block that this Tile Entity is associated with. + /// public int X { get { return _x; } set { _x = value; } } + /// + /// Gets or sets the global Y-coordinate of the block that this Tile Entity is associated with. + /// public int Y { get { return _y; } set { _y = value; } } + /// + /// Gets or sets the global Z-coordinate of the block that this Tile Entity is associated with. + /// public int Z { get { return _z; } set { _z = value; } } + /// + /// Constructs a nonspecific with a given ID. + /// + /// The id (name) of the Tile Entity. public TileEntity (string id) { _id = id; } + /// + /// Constructs a by copying an existing one. + /// + /// The to copy. public TileEntity (TileEntity te) { _id = te._id; @@ -58,6 +82,13 @@ namespace Substrate _z = te._z; } + /// + /// Checks whether the Tile Entity is located (associated with a block) at the specific global coordinates. + /// + /// The global X-coordinate to test. + /// The global Y-coordinate to test. + /// The global Z-coordinate to test. + /// Status indicating whether the Tile Entity is located at the specified global coordinates. public bool LocatedAt (int x, int y, int z) { return _x == x && _y == y && _z == z; @@ -66,6 +97,10 @@ namespace Substrate #region ICopyable Members + /// + /// Creates a deep-copy of the including any data defined in a subtype. + /// + /// A deep-copy of the . public virtual TileEntity Copy () { return new TileEntity(this); @@ -76,6 +111,19 @@ namespace Substrate #region INBTObject Members + /// + /// Gets a representing the basic schema of a Tile Entity. + /// + public static SchemaNodeCompound Schema + { + get { return _schema; } + } + + /// + /// Attempt to load a Tile Entity subtree into the without validation. + /// + /// The root node of a Tile Entity subtree. + /// The returns itself on success, or null if the tree was unparsable. public virtual TileEntity LoadTree (TagNode tree) { TagNodeCompound ctree = tree as TagNodeCompound; @@ -91,6 +139,11 @@ namespace Substrate return this; } + /// + /// Attempt to load a Tile Entity subtree into the with validation. + /// + /// The root node of a Tile Entity subtree. + /// The returns itself on success, or null if the tree failed validation. public virtual TileEntity LoadTreeSafe (TagNode tree) { if (!ValidateTree(tree)) { @@ -100,6 +153,10 @@ namespace Substrate return LoadTree(tree); } + /// + /// Builds a Tile Entity subtree from the current data. + /// + /// The root node of a Tile Entity subtree representing the current data. public virtual TagNode BuildTree () { TagNodeCompound tree = new TagNodeCompound(); @@ -111,9 +168,14 @@ namespace Substrate return tree; } + /// + /// Validate a Tile Entity subtree against a basic schema. + /// + /// The root node of a Tile Entity subtree. + /// Status indicating whether the tree was valid against the internal schema. public virtual bool ValidateTree (TagNode tree) { - return new NBTVerifier(tree, BaseSchema).Verify(); + return new NBTVerifier(tree, _schema).Verify(); } #endregion diff --git a/Substrate/SubstrateCS/Source/TileEntityFactory.cs b/Substrate/SubstrateCS/Source/TileEntityFactory.cs index aa03a0e..9eb2431 100644 --- a/Substrate/SubstrateCS/Source/TileEntityFactory.cs +++ b/Substrate/SubstrateCS/Source/TileEntityFactory.cs @@ -1,16 +1,26 @@ using System; using System.Collections.Generic; -using System.Text; namespace Substrate { using NBT; using TileEntities; + /// + /// Creates new instances of concrete types from a dynamic registry. + /// + /// This factory allows specific objects to be generated as an NBT tree is parsed. New types can be + /// registered with the factory at any time, so that custom types can be supported. By default, the standard + /// Tile Entities of Minecraft are registered with the factory at startup and bound to their respective 'id' fields. public class TileEntityFactory { private static Dictionary _registry; + /// + /// Create a new instance of a concrete type by name. + /// + /// The name that a concrete type was registered with. + /// A new instance of a concrete type, or null if no type was registered with the given name. public static TileEntity Create (string type) { Type t; @@ -21,6 +31,11 @@ namespace Substrate return Activator.CreateInstance(t) as TileEntity; } + /// + /// Create a new instance of a concrete type by NBT node. + /// + /// A representing a single Tile Entity, containing an 'id' field of the Tile Entity's registered name. + /// A new instance of a concrete type, or null if no type was registered with the given name. public static TileEntity Create (TagNodeCompound tree) { string type = tree["id"].ToTagString(); @@ -35,6 +50,11 @@ namespace Substrate return te.LoadTreeSafe(tree); } + /// + /// Lookup a concrete type by name. + /// + /// The name that a concrete type was registered with. + /// The of a concrete type, or null if no type was registered with the given name. public static Type Lookup (string type) { Type t; @@ -45,6 +65,11 @@ namespace Substrate return t; } + /// + /// Registers a new concrete type with the , binding it to a given name. + /// + /// The name to bind to a concrete type. + /// The of a concrete type. public static void Register (string id, Type subtype) { _registry[id] = subtype;