From 0fefa0d6407fa676a8a7b0103ac6eb8e9f056cc2 Mon Sep 17 00:00:00 2001 From: Justin Aquadro Date: Sat, 18 Jun 2011 03:01:39 +0000 Subject: [PATCH] Documentation --- Substrate/SubstrateCS/Source/Chunk.cs | 77 ++++++++++++++++++++++++ Substrate/SubstrateCS/Source/ChunkRef.cs | 6 +- 2 files changed, 81 insertions(+), 2 deletions(-) diff --git a/Substrate/SubstrateCS/Source/Chunk.cs b/Substrate/SubstrateCS/Source/Chunk.cs index bd408f7..dd6afea 100644 --- a/Substrate/SubstrateCS/Source/Chunk.cs +++ b/Substrate/SubstrateCS/Source/Chunk.cs @@ -7,12 +7,21 @@ namespace Substrate using NBT; using Utility; + /// + /// A Minecraft Alpha-compatible chunk data structure. + /// + /// + /// A Chunk internally wraps an NBT_Tree of raw chunk data. Modifying the chunk will update the tree, and vice-versa. + /// public class Chunk : IChunk, INBTObject, ICopyable { private const int XDIM = 16; private const int YDIM = 128; private const int ZDIM = 16; + /// + /// An NBT Schema definition for valid chunk data. + /// public static NBTCompoundNode LevelSchema = new NBTCompoundNode() { new NBTCompoundNode("Level") @@ -48,41 +57,66 @@ namespace Substrate private AlphaBlockCollection _blockManager; private EntityCollection _entityManager; + /// + /// Gets the global X-coordinate of the chunk. + /// public int X { get { return _cx; } } + /// + /// Gets the global Z-coordinate of the chunk. + /// public int Z { get { return _cz; } } + /// + /// Gets the collection of all blocks and their data stored in the chunk. + /// public AlphaBlockCollection Blocks { get { return _blockManager; } } + /// + /// Gets the collection of all entities stored in the chunk. + /// public EntityCollection Entities { get { return _entityManager; } } + /// + /// Provides raw access to the underlying NBT_Tree. + /// public NBT_Tree Tree { get { return _tree; } } + /// + /// Gets or sets the chunk's TerrainPopulated status. + /// public bool IsTerrainPopulated { get { return _tree.Root["Level"].ToTagCompound()["TerrainPopulated"].ToTagByte() == 1; } set { _tree.Root["Level"].ToTagCompound()["TerrainPopulated"].ToTagByte().Data = (byte)(value ? 1 : 0); } } + private Chunk () { } + /// + /// Creates a default (empty) chunk. + /// + /// Global X-coordinate of the chunk. + /// Global Z-coordinate of the chunk. + /// A new Chunk object. public static Chunk Create (int x, int z) { Chunk c = new Chunk(); @@ -95,6 +129,11 @@ namespace Substrate return c; } + /// + /// Creates a chunk object from an existing NBT_Tree. + /// + /// An NBT_Tree conforming to the chunk schema definition. + /// A new Chunk object wrapping an existing NBT_Tree. public static Chunk Create (NBT_Tree tree) { Chunk c = new Chunk(); @@ -102,6 +141,11 @@ namespace Substrate return c.LoadTree(tree.Root); } + /// + /// Creates a chunk object from a verified NBT_Tree. + /// + /// An NBT_Tree conforming to the chunk schema definition. + /// A new Chunk object wrapping an existing NBT_Tree, or null on verification failure. public static Chunk CreateVerified (NBT_Tree tree) { Chunk c = new Chunk(); @@ -109,12 +153,22 @@ namespace Substrate return c.LoadTreeSafe(tree.Root); } + /// + /// Updates the chunk's global world coordinates. + /// + /// Global X-coordinate. + /// Global Z-coordinate. public virtual void SetLocation (int x, int z) { _cx = x; _cz = z; } + /// + /// Saves a Chunk's underlying NBT_Tree to an output stream. + /// + /// An open, writable output stream. + /// True if the data is written out to the stream. public bool Save (Stream outStream) { if (outStream == null || !outStream.CanWrite) { @@ -130,6 +184,11 @@ namespace Substrate #region INBTObject Members + /// + /// Loads the Chunk from an NBT tree rooted at the given TagValue node. + /// + /// Root node of an NBT tree. + /// A reference to the current Chunk, or null if the tree is unparsable. public Chunk LoadTree (TagValue tree) { TagCompound ctree = tree as TagCompound; @@ -176,6 +235,11 @@ namespace Substrate return this; } + /// + /// Loads the Chunk from a validated NBT tree rooted at the given TagValue node. + /// + /// Root node of an NBT tree. + /// A reference to the current Chunk, or null if the tree does not conform to the chunk's NBT Schema definition. public Chunk LoadTreeSafe (TagValue tree) { if (!ValidateTree(tree)) { @@ -185,11 +249,20 @@ namespace Substrate return LoadTree(tree); } + /// + /// Gets a valid NBT tree representing the Chunk. + /// + /// The root node of the Chunk's NBT tree. public TagValue BuildTree () { return _tree.Root; } + /// + /// Validates an NBT tree against the chunk's NBT schema definition. + /// + /// The root node of the NBT tree to verify. + /// Status indicating if the tree represents a valid chunk. public bool ValidateTree (TagValue tree) { NBTVerifier v = new NBTVerifier(tree, LevelSchema); @@ -201,6 +274,10 @@ namespace Substrate #region ICopyable Members + /// + /// Creates a deep copy of the Chunk and its underlying NBT tree. + /// + /// A new Chunk with copied data. public Chunk Copy () { return Chunk.Create(_tree.Copy()); diff --git a/Substrate/SubstrateCS/Source/ChunkRef.cs b/Substrate/SubstrateCS/Source/ChunkRef.cs index 34da2ef..6a5458f 100644 --- a/Substrate/SubstrateCS/Source/ChunkRef.cs +++ b/Substrate/SubstrateCS/Source/ChunkRef.cs @@ -5,9 +5,11 @@ using System.Collections.Generic; namespace Substrate { /// - /// Provides a wrapper around a physical Chunk stored in a chunk container. Modifying data in a ChunkRef will signal to the chunk - /// container that the physical chunk needs to be saved. + /// Provides a wrapper around a physical Chunk stored in a chunk container. /// + /// + /// Modifying data in a ChunkRef will signal to the chunk container that the physical chunk needs to be saved. + /// public class ChunkRef : IChunk { private IChunkContainer _container;