From 79cd9afa7b415034bec50e8d15f42e88056dc0e3 Mon Sep 17 00:00:00 2001 From: Justin Aquadro Date: Fri, 17 Jun 2011 04:41:08 +0000 Subject: [PATCH] Begging to incorporate inline documentation. --- Substrate/SubstrateCS/Source/ChunkRef.cs | 102 +++++++++++++++++- .../SubstrateCS/Source/NBT/JSONSerializer.cs | 8 ++ Substrate/SubstrateCS/Source/Utility/Base.cs | 27 +++++ Substrate/SubstrateCS/Substrate.csproj | 6 +- 4 files changed, 138 insertions(+), 5 deletions(-) diff --git a/Substrate/SubstrateCS/Source/ChunkRef.cs b/Substrate/SubstrateCS/Source/ChunkRef.cs index fd5099f..34da2ef 100644 --- a/Substrate/SubstrateCS/Source/ChunkRef.cs +++ b/Substrate/SubstrateCS/Source/ChunkRef.cs @@ -4,6 +4,10 @@ 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. + /// public class ChunkRef : IChunk { private IChunkContainer _container; @@ -17,26 +21,41 @@ namespace Substrate private bool _dirty; + /// + /// Gets the global X-coordinate of the chunk. + /// public int X { get { return _container.ChunkGlobalX(_cx); } } + /// + /// Gets the global Z-coordinate of the chunk. + /// public int Z { get { return _container.ChunkGlobalZ(_cz); } } + /// + /// Gets the local X-coordinate of the chunk within container. + /// public int LocalX { get { return _container.ChunkLocalX(_cx); } } + /// + /// Gets the local Z-coordinate of the chunk within container. + /// public int LocalZ { get { return _container.ChunkLocalZ(_cz); } } + /// + /// Gets the collection of all blocks and their data stored in the chunk. + /// public AlphaBlockCollection Blocks { get @@ -48,6 +67,9 @@ namespace Substrate } } + /// + /// Gets the collection of all entities stored in the chunk. + /// public EntityCollection Entities { get @@ -59,6 +81,9 @@ namespace Substrate } } + /// + /// Gets or sets the value indicating that the chunk has been modified, but not saved. + /// public bool IsDirty { get @@ -78,10 +103,20 @@ namespace Substrate } } + /// + /// Forbid direct instantiation of ChunkRef objects + /// private ChunkRef () { } + /// + /// Create a reference to a chunk stored in a chunk container. + /// + /// Chunk container + /// Local X-coordinate of chunk within container. + /// Local Z-coordinate of chunk within container. + /// ChunkRef representing a reference to a physical chunk at the specified location within the container. public static ChunkRef Create (IChunkContainer container, int cx, int cz) { if (!container.ChunkExists(cx, cz)) { @@ -97,6 +132,9 @@ namespace Substrate return c; } + /// + /// Gets or sets the chunk's TerrainPopulated status. + /// public bool IsTerrainPopulated { get { return GetChunk().IsTerrainPopulated; } @@ -109,6 +147,11 @@ namespace Substrate } } + /// + /// Saves the underlying physical chunk to the specified output stream. + /// + /// An open output stream. + /// A value indicating whether the chunk is no longer considered dirty. public bool Save (Stream outStream) { if (IsDirty) { @@ -121,31 +164,62 @@ namespace Substrate return true; } + /// + /// Gets a ChunkRef to the chunk positioned immediately north (X - 1). + /// + /// ChunkRef to the northern neighboring chunk. public ChunkRef GetNorthNeighbor () { return _container.GetChunkRef(_cx - 1, _cz); } + /// + /// Gets a ChunkRef to the chunk positioned immediately south (X + 1). + /// + /// ChunkRef to the southern neighboring chunk. public ChunkRef GetSouthNeighbor () { return _container.GetChunkRef(_cx + 1, _cz); } + /// + /// Gets a ChunkRef to the chunk positioned immediatly east (Z - 1). + /// + /// ChunkRef to the eastern neighboring chunk. public ChunkRef GetEastNeighbor () { return _container.GetChunkRef(_cx, _cz - 1); } + /// + /// Gets a ChunkRef to the chunk positioned immedately west (Z + 1). + /// + /// ChunkRef to the western neighboring chunk. public ChunkRef GetWestNeighbor () { return _container.GetChunkRef(_cx, _cz + 1); } + /// + /// Returns a deep copy of the physical chunk underlying the ChunkRef. + /// + /// A copy of the physical Chunk object. public Chunk GetChunkCopy () { return GetChunk().Copy(); } + /// + /// Returns the reference of the physical chunk underlying the ChunkRef, and releases the reference from itself. + /// + /// + /// This function returns the reference to the chunk stored in the chunk container. Because the ChunkRef simultaneously gives up + /// its "ownership" of the Chunk, the container will not consider the Chunk dirty even if it is modified. Attempting to use the ChunkRef after + /// releasing its internal reference will query the container for a new reference. If the chunk is still cached, it will get the same reference + /// back, otherwise it will get an independent copy. Chunks should only be taken from ChunkRefs to transfer them to another ChunkRef, or + /// to modify them without intending to permanently store the changes. + /// + /// The physical Chunk object underlying the ChunkRef public Chunk GetChunkRef () { Chunk chunk = GetChunk(); @@ -155,6 +229,14 @@ namespace Substrate return chunk; } + /// + /// Replaces the underlying physical chunk with a different one, updating its physical location to reflect the ChunkRef. + /// + /// + /// Use this function to save chunks that have been created or manipulated independently of a container, or to + /// move a physical chunk between locations within a container (by taking the reference from another ChunkRef). + /// + /// Physical Chunk to store into the location represented by this ChunkRef. public void SetChunkRef (Chunk chunk) { _chunk = chunk; @@ -162,7 +244,10 @@ namespace Substrate _dirty = true; } - + /// + /// Gets an internal Chunk reference from cache or queries the container for it. + /// + /// The ChunkRef's underlying Chunk. private Chunk GetChunk () { if (_chunk == null) { @@ -172,6 +257,7 @@ namespace Substrate _blocks = _chunk.Blocks; _entities = _chunk.Entities; + // Set callback functions in the underlying block collection _blocks.ResolveNeighbor += ResolveNeighborHandler; _blocks.TranslateCoordinates += TranslateCoordinatesHandler; } @@ -179,6 +265,13 @@ namespace Substrate return _chunk; } + /// + /// Callback function to return the block collection of a ChunkRef at a relative offset to this one. + /// + /// Relative offset from the X-coordinate. + /// Relative offset from the Y-coordinate. + /// Relative offset from the Z-coordinate. + /// Another ChunkRef's underlying block collection, or null if the ChunkRef cannot be found. private AlphaBlockCollection ResolveNeighborHandler (int relx, int rely, int relz) { ChunkRef cr = _container.GetChunkRef(_cx + relx, _cz + relz); @@ -189,6 +282,13 @@ namespace Substrate return null; } + /// + /// Translates chunk-local block coordinates to corresponding global coordinates. + /// + /// Chunk-local X-coordinate. + /// Chunk-local Y-coordinate. + /// Chunk-local Z-coordinate. + /// BlockKey containing the global block coordinates. private BlockKey TranslateCoordinatesHandler (int lx, int ly, int lz) { int x = X * _blocks.XDim + lx; diff --git a/Substrate/SubstrateCS/Source/NBT/JSONSerializer.cs b/Substrate/SubstrateCS/Source/NBT/JSONSerializer.cs index 35f779b..c8c4c18 100644 --- a/Substrate/SubstrateCS/Source/NBT/JSONSerializer.cs +++ b/Substrate/SubstrateCS/Source/NBT/JSONSerializer.cs @@ -4,6 +4,8 @@ using System.Text; namespace Substrate.NBT { + using Substrate.Utility; + public class JSONSerializer { public static string Serialize (TagValue tag) @@ -140,6 +142,12 @@ namespace Substrate.NBT case TagType.TAG_BYTE_ARRAY: str.Append(Convert.ToBase64String(tag.ToTagByteArray().Data)); + /*if (tag.ToTagByteArray().Length == (16 * 16 * 128 / 2)) { + str.Append(Base16.Encode(tag.ToTagByteArray().Data, 1)); + } + else { + str.Append(Base16.Encode(tag.ToTagByteArray().Data, 2)); + }*/ break; } } diff --git a/Substrate/SubstrateCS/Source/Utility/Base.cs b/Substrate/SubstrateCS/Source/Utility/Base.cs index ef2f373..703b2b8 100644 --- a/Substrate/SubstrateCS/Source/Utility/Base.cs +++ b/Substrate/SubstrateCS/Source/Utility/Base.cs @@ -60,4 +60,31 @@ namespace Substrate.Utility return result; } } + + public static class Base16 + { + private const string _alphabet = "0123456789abcdef"; + + public static string Encode (byte[] input, int stride = 0, char strideChar = ' ') + { + List result = new List(); + + for (int i = 0; i < input.Length; i++) { + int hi = (input[i] >> 4) & 0xF; + int lo = input[i] & 0xF; + + result.Add(_alphabet[hi]); + if (stride > 0 && (((i + 1) * 2 - 1) % stride) == 0) { + result.Add(strideChar); + } + + result.Add(_alphabet[lo]); + if (stride > 0 && (((i + 1) * 2) % stride) == 0) { + result.Add(strideChar); + } + } + + return new string(result.ToArray()); + } + } } diff --git a/Substrate/SubstrateCS/Substrate.csproj b/Substrate/SubstrateCS/Substrate.csproj index e618d2c..394ce3e 100644 --- a/Substrate/SubstrateCS/Substrate.csproj +++ b/Substrate/SubstrateCS/Substrate.csproj @@ -43,8 +43,7 @@ DEBUG;TRACE prompt 4 - - + Substrate.xml pdbonly @@ -53,8 +52,7 @@ TRACE prompt 4 - - + Substrate.xml