amethyst/NBTExplorer
1
0
Fork 0
forked from mirrors/NBTExplorer
Code Pull requests Activity

Begging to incorporate inline documentation.

Browse source
This commit is contained in:
Justin Aquadro 2011-06-17 04:41:08 +00:00
parent 821acda42a
commit 79cd9afa7b
4 changed files with 138 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
Substrate/SubstrateCS/Source/ChunkRef.cs
View file

@ -4,6 +4,10 @@ using System.Collections.Generic;
namespace Substrate
{
/// <summary>
/// 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.
/// </summary>
public class ChunkRef : IChunk
{
private IChunkContainer _container;
@ -17,26 +21,41 @@ namespace Substrate
private bool _dirty;
/// <summary>
/// Gets the global X-coordinate of the chunk.
/// </summary>
public int X
{
get { return _container.ChunkGlobalX(_cx); }
}
/// <summary>
/// Gets the global Z-coordinate of the chunk.
/// </summary>
public int Z
{
get { return _container.ChunkGlobalZ(_cz); }
}
/// <summary>
/// Gets the local X-coordinate of the chunk within container.
/// </summary>
public int LocalX
{
get { return _container.ChunkLocalX(_cx); }
}
/// <summary>
/// Gets the local Z-coordinate of the chunk within container.
/// </summary>
public int LocalZ
{
get { return _container.ChunkLocalZ(_cz); }
}
/// <summary>
/// Gets the collection of all blocks and their data stored in the chunk.
/// </summary>
public AlphaBlockCollection Blocks
{
get
@ -48,6 +67,9 @@ namespace Substrate
}
}
/// <summary>
/// Gets the collection of all entities stored in the chunk.
/// </summary>
public EntityCollection Entities
{
get
@ -59,6 +81,9 @@ namespace Substrate
}
}
/// <summary>
/// Gets or sets the value indicating that the chunk has been modified, but not saved.
/// </summary>
public bool IsDirty
{
get
@ -78,10 +103,20 @@ namespace Substrate
}
}
/// <summary>
/// Forbid direct instantiation of ChunkRef objects
/// </summary>
private ChunkRef ()
{
}
/// <summary>
/// Create a reference to a chunk stored in a chunk container.
/// </summary>
/// <param name="container">Chunk container</param>
/// <param name="cx">Local X-coordinate of chunk within container.</param>
/// <param name="cz">Local Z-coordinate of chunk within container.</param>
/// <returns>ChunkRef representing a reference to a physical chunk at the specified location within the container.</returns>
public static ChunkRef Create (IChunkContainer container, int cx, int cz)
{
if (!container.ChunkExists(cx, cz)) {
@ -97,6 +132,9 @@ namespace Substrate
return c;
}
/// <summary>
/// Gets or sets the chunk's TerrainPopulated status.
/// </summary>
public bool IsTerrainPopulated
{
get { return GetChunk().IsTerrainPopulated; }
@ -109,6 +147,11 @@ namespace Substrate
}
}
/// <summary>
/// Saves the underlying physical chunk to the specified output stream.
/// </summary>
/// <param name="outStream">An open output stream.</param>
/// <returns>A value indicating whether the chunk is no longer considered dirty.</returns>
public bool Save (Stream outStream)
{
if (IsDirty) {
@ -121,31 +164,62 @@ namespace Substrate
return true;
}
/// <summary>
/// Gets a ChunkRef to the chunk positioned immediately north (X - 1).
/// </summary>
/// <returns>ChunkRef to the northern neighboring chunk.</returns>
public ChunkRef GetNorthNeighbor ()
{
return _container.GetChunkRef(_cx - 1, _cz);
}
/// <summary>
/// Gets a ChunkRef to the chunk positioned immediately south (X + 1).
/// </summary>
/// <returns>ChunkRef to the southern neighboring chunk.</returns>
public ChunkRef GetSouthNeighbor ()
{
return _container.GetChunkRef(_cx + 1, _cz);
}
/// <summary>
/// Gets a ChunkRef to the chunk positioned immediatly east (Z - 1).
/// </summary>
/// <returns>ChunkRef to the eastern neighboring chunk.</returns>
public ChunkRef GetEastNeighbor ()
{
return _container.GetChunkRef(_cx, _cz - 1);
}
/// <summary>
/// Gets a ChunkRef to the chunk positioned immedately west (Z + 1).
/// </summary>
/// <returns>ChunkRef to the western neighboring chunk.</returns>
public ChunkRef GetWestNeighbor ()
{
return _container.GetChunkRef(_cx, _cz + 1);
}
/// <summary>
/// Returns a deep copy of the physical chunk underlying the ChunkRef.
/// </summary>
/// <returns>A copy of the physical Chunk object.</returns>
public Chunk GetChunkCopy ()
{
return GetChunk().Copy();
}
/// <summary>
/// Returns the reference of the physical chunk underlying the ChunkRef, and releases the reference from itself.
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
/// <returns>The physical Chunk object underlying the ChunkRef</returns>
public Chunk GetChunkRef ()
{
Chunk chunk = GetChunk();
@ -155,6 +229,14 @@ namespace Substrate
return chunk;
}
/// <summary>
/// Replaces the underlying physical chunk with a different one, updating its physical location to reflect the ChunkRef.
/// </summary>
/// <remarks>
/// 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).
/// </remarks>
/// <param name="chunk">Physical Chunk to store into the location represented by this ChunkRef.</param>
public void SetChunkRef (Chunk chunk)
{
_chunk = chunk;
@ -162,7 +244,10 @@ namespace Substrate
_dirty = true;
}
/// <summary>
/// Gets an internal Chunk reference from cache or queries the container for it.
/// </summary>
/// <returns>The ChunkRef's underlying Chunk.</returns>
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;
}
/// <summary>
/// Callback function to return the block collection of a ChunkRef at a relative offset to this one.
/// </summary>
/// <param name="relx">Relative offset from the X-coordinate.</param>
/// <param name="rely">Relative offset from the Y-coordinate.</param>
/// <param name="relz">Relative offset from the Z-coordinate.</param>
/// <returns>Another ChunkRef's underlying block collection, or null if the ChunkRef cannot be found.</returns>
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;
}
/// <summary>
/// Translates chunk-local block coordinates to corresponding global coordinates.
/// </summary>
/// <param name="lx">Chunk-local X-coordinate.</param>
/// <param name="ly">Chunk-local Y-coordinate.</param>
/// <param name="lz">Chunk-local Z-coordinate.</param>
/// <returns>BlockKey containing the global block coordinates.</returns>
private BlockKey TranslateCoordinatesHandler (int lx, int ly, int lz)
{
int x = X * _blocks.XDim + lx;

8
Substrate/SubstrateCS/Source/NBT/JSONSerializer.cs
View file

@ -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;
}
}

27
Substrate/SubstrateCS/Source/Utility/Base.cs
View file

@ -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<char> result = new List<char>();
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());
}
}
}

6
Substrate/SubstrateCS/Substrate.csproj
View file

@ -43,8 +43,7 @@
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<DocumentationFile>
</DocumentationFile>
<DocumentationFile>Substrate.xml</DocumentationFile>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
@ -53,8 +52,7 @@
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<DocumentationFile>
</DocumentationFile>
<DocumentationFile>Substrate.xml</DocumentationFile>
</PropertyGroup>
<ItemGroup>
<Reference Include="Ionic.Zlib, Version=1.0.0.0, Culture=neutral, processorArchitecture=MSIL">