block interface model revision

Substrate/SubstrateCS/Source/AlphaBlock.cs

@@ -142,6 +142,21 @@ namespace Substrate
             _tileEntity = te;
         }
 
+        public void CreateTileEntity ()
+        {
+            BlockInfoEx info = BlockInfo.BlockTable[_id] as BlockInfoEx;
+            if (info == null) {
+                throw new InvalidOperationException("The given block is of a type that does not support TileEntities.");
+            }
+
+            TileEntity te = TileEntityFactory.Create(info.TileEntityName);
+            if (te == null) {
+                throw new UnknownTileEntityException("The TileEntity type '" + info.TileEntityName + "' has not been registered with the TileEntityFactory.");
+            }
+
+            _tileEntity = te;
+        }
+
         /// <summary>
         /// Removes any Tile Entity currently attached to the block.
         /// </summary>

Substrate/SubstrateCS/Source/AlphaBlockCollection.cs

@@ -171,77 +171,43 @@ namespace Substrate
             SetTileEntity(x, y, z, block.GetTileEntity().Copy());
         }
 
-        #region IBlockCollection Members
+        #region IBoundedBlockCollection Members
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the length of this collection's X-dimension.
-        /// </summary>
         public int XDim
         {
             get { return _xdim; }
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the length of this collection's Y-dimension.
-        /// </summary>
         public int YDim
         {
             get { return _ydim; }
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the length of this collection's Z-dimension.
-        /// </summary>
         public int ZDim
         {
             get { return _zdim; }
         }
 
-        /// <summary>
+        IBlock IBoundedBlockCollection.GetBlock (int x, int y, int z)
-        /// Returns an object compatible with the <see cref="IBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IBlock"/>-compatible object.</returns>
-        /// <seealso cref="AlphaBlock"/>
-        IBlock IBlockCollection.GetBlock (int x, int y, int z)
         {
             return GetBlock(x, y, z);
         }
 
-        /// <summary>
+        IBlock IBoundedBlockCollection.GetBlockRef (int x, int y, int z)
-        /// Returns a reference object compatible with the <see cref="IBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IBlock"/>-compatible reference object.</returns>
-        /// <seealso cref="AlphaBlockRef"/>
-        IBlock IBlockCollection.GetBlockRef (int x, int y, int z)
         {
             return GetBlockRef(x, y, z);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates a block in this collection with values from an <see cref="IBlock"/> object.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="block">An <see cref="IBlock"/> object to copy block data from.</param>
         public void SetBlock (int x, int y, int z, IBlock block)
         {
             SetID(x, y, z, block.ID);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets information on the type of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>A <see cref="BlockInfo"/> object containing information of a block's type.</returns>
         public BlockInfo GetInfo (int x, int y, int z)
         {
             return BlockInfo.BlockTable[_blocks[x, y, z]];
@@ -252,13 +218,7 @@ namespace Substrate
             return BlockInfo.BlockTable[_blocks[index]];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the ID (type) of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>The ID (type) of the specified block.</returns>
         public int GetID (int x, int y, int z)
         {
             return _blocks[x, y, z];
@@ -269,13 +229,7 @@ namespace Substrate
             return _blocks[index];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets the ID (type) of a block at the given local coordinates, maintaining consistency of data.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="id">The new ID of the block.</param>
         /// <remarks>Depending on the options set for this <see cref="AlphaBlockCollection"/>, this method can be very
         /// heavy-handed in the amount of work it does to maintain consistency of tile entities, lighting, fluid, etc.
         /// for the affected block and possibly many other indirectly-affected blocks in the collection or neighboring
@@ -345,11 +299,7 @@ namespace Substrate
             SetID(x, y, z, id);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Returns a count of all blocks in this <see cref="AlphaBlockCollection"/> with the given ID (type).
-        /// </summary>
-        /// <param name="id">The ID of blocks to count.</param>
-        /// <returns>A count of all matching blocks.</returns>
         public int CountByID (int id)
         {
             int c = 0;
@@ -365,54 +315,26 @@ namespace Substrate
         #endregion
 
 
-        #region IDataBlockContainer Members
+        #region IBoundedDataBlockContainer Members
 
-        /// <summary>
+        IDataBlock IBoundedDataBlockCollection.GetBlock (int x, int y, int z)
-        /// Returns an object compatible with the <see cref="IDataBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IDataBlock"/>-compatible object.</returns>
-        /// <seealso cref="AlphaBlock"/>
-        IDataBlock IDataBlockCollection.GetBlock (int x, int y, int z)
         {
             return GetBlock(x, y, z);
         }
 
-        /// <summary>
+        IDataBlock IBoundedDataBlockCollection.GetBlockRef (int x, int y, int z)
-        /// Returns a reference object compatible with the <see cref="IDataBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IDataBlock"/>-compatible reference object.</returns>
-        /// <seealso cref="AlphaBlockRef"/>
-        IDataBlock IDataBlockCollection.GetBlockRef (int x, int y, int z)
         {
             return GetBlockRef(x, y, z);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates a block in this collection with values from an <see cref="IDataBlock"/> object.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="block">An <see cref="IDataBlock"/> object to copy block data from.</param>
         public void SetBlock (int x, int y, int z, IDataBlock block)
         {
             SetID(x, y, z, block.ID);
             SetData(x, y, z, block.Data);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the data value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>The data value of the specified block.</returns>
         public int GetData (int x, int y, int z)
         {
             return _data[x, y, z];
@@ -423,13 +345,7 @@ namespace Substrate
             return _data[index];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets the data value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="data">The new data value of the block.</param>
         public void SetData (int x, int y, int z, int data)
         {
             if (_data[x, y, z] != data) {
@@ -452,12 +368,7 @@ namespace Substrate
             }
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Returns a count of all blocks in this <see cref="AlphaBlockCollection"/> matching the given ID (type) and data value.
-        /// </summary>
-        /// <param name="id">The ID of blocks to count.</param>
-        /// <param name="data">The data value of blocks to count.</param>
-        /// <returns>A count of all matching blocks.</returns>
         public int CountByData (int id, int data)
         {
             int c = 0;
@@ -473,41 +384,19 @@ namespace Substrate
         #endregion
 
 
-        #region ILitBlockCollection Members
+        #region IBoundedLitBlockCollection Members
 
-        /// <summary>
+        ILitBlock IBoundedLitBlockCollection.GetBlock (int x, int y, int z)
-        /// Not Implemented.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="ILitBlock"/>-compatible object.</returns>
-        /// <seealso cref="AlphaBlock"/>
-        ILitBlock ILitBlockCollection.GetBlock (int x, int y, int z)
         {
             throw new NotImplementedException();
         }
 
-        /// <summary>
+        ILitBlock IBoundedLitBlockCollection.GetBlockRef (int x, int y, int z)
-        /// Returns a reference object compatible with the <see cref="ILitBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="ILitBlock"/>-compatible reference object.</returns>
-        /// <seealso cref="AlphaBlockRef"/>
-        ILitBlock ILitBlockCollection.GetBlockRef (int x, int y, int z)
         {
             return GetBlockRef(x, y, z);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates a block in this collection with values from an <see cref="ILitBlock"/> object.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="block">An <see cref="ILitBlock"/> object to copy block data from.</param>
         public void SetBlock (int x, int y, int z, ILitBlock block)
         {
             SetID(x, y, z, block.ID);
@@ -515,13 +404,7 @@ namespace Substrate
             SetSkyLight(x, y, z, block.SkyLight);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the block-source light value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>The block-source light value of the specified block.</returns>
         public int GetBlockLight (int x, int y, int z)
         {
             return _blockLight[x, y, z];
@@ -532,13 +415,7 @@ namespace Substrate
             return _blockLight[index];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the sky-source light value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>The sky-source light value of the specified block.</returns>
         public int GetSkyLight (int x, int y, int z)
         {
             return _skyLight[x, y, z];
@@ -549,13 +426,7 @@ namespace Substrate
             return _skyLight[index];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets the blocks-source light value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="light">The new block-source light value of the block.</param>
         public void SetBlockLight (int x, int y, int z, int light)
         {
             if (_blockLight[x, y, z] != light) {
@@ -572,13 +443,7 @@ namespace Substrate
             }
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets the sky-source light value of a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="light">The new sky-source light value of the block.</param>
         public void SetSkyLight (int x, int y, int z, int light)
         {
             if (_skyLight[x, y, z] != light) {
@@ -595,34 +460,19 @@ namespace Substrate
             }
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets the lowest Y-coordinate of a block at which sky-source light remains unfiltered.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a map location.</param>
-        /// <param name="z">Local Z-coordinate of a map location.</param>
-        /// <returns>The height-map value of a map location for calculating sky-source lighting.</returns>
         public int GetHeight (int x, int z)
         {
             return _heightMap[x, z];
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets the lowest Y-coordinate of a block at which sky-source light remains unfiltered.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a map location.</param>
-        /// <param name="z">Local Z-coordinate of a map location.</param>
-        /// <param name="height">The new height-map value of the given map location.</param>
         public void SetHeight (int x, int z, int height)
         {
             _heightMap[x, z] = (byte)height;
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates the block-source lighting of a block at the given local coordinates to maintain light consistency.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
         /// <remarks><para>The lighting of the block will be updated to be consistent with the lighting in neighboring blocks.
         /// If the block is itself a light source, many nearby blocks may be updated to maintain consistent lighting.  These
         /// updates may also touch neighboring <see cref="AlphaBlockCollection"/> objects, if they can be resolved.</para>
@@ -635,12 +485,7 @@ namespace Substrate
             _dirty = true;
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates the sky-source lighting of a block at the given local coordinates to maintain light consistency.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
         /// <remarks><para>The lighting of the block will be updated to be consistent with the lighting in neighboring blocks.
         /// If the block is itself a light source, many nearby blocks may be updated to maintain consistent lighting.  These
         /// updates may also touch neighboring <see cref="AlphaBlockCollection"/> objects, if they can be resolved.</para>
@@ -771,54 +616,26 @@ namespace Substrate
         #endregion
 
 
-        #region IPropertyBlockCollection Members
+        #region IBoundedPropertyBlockCollection Members
 
-        /// <summary>
+        IPropertyBlock IBoundedPropertyBlockCollection.GetBlock (int x, int y, int z)
-        /// Returns an object compatible with the <see cref="IPropertyBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IPropertyBlock"/>-compatible object.</returns>
-        /// <seealso cref="AlphaBlock"/>
-        IPropertyBlock IPropertyBlockCollection.GetBlock (int x, int y, int z)
         {
             return GetBlock(x, y, z);
         }
 
-        /// <summary>
+        IPropertyBlock IBoundedPropertyBlockCollection.GetBlockRef (int x, int y, int z)
-        /// Returns a reference object compatible with the <see cref="IPropertyBlock"/> interface from local coordinates relative to this collection.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>An <see cref="IPropertyBlock"/>-compatible reference object.</returns>
-        /// <seealso cref="AlphaBlockRef"/>
-        IPropertyBlock IPropertyBlockCollection.GetBlockRef (int x, int y, int z)
         {
             return GetBlockRef(x, y, z);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Updates a block in this collection with values from an <see cref="IPropertyBlock"/> object.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="block">An <see cref="IPropertyBlock"/> object to copy block data from.</param>
         public void SetBlock (int x, int y, int z, IPropertyBlock block)
         {
             SetID(x, y, z, block.ID);
             SetTileEntity(x, y, z, block.GetTileEntity().Copy());
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Gets a <see cref="TileEntity"/> record for a block at the given local coordinates, if one exists.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <returns>A <see cref="TileEntity"/> for the given block, or null if the <see cref="TileEntity"/> is missing or the block type does not use a <see cref="TileEntity"/>.</returns>
         public TileEntity GetTileEntity (int x, int y, int z)
         {
             return _tileEntityManager.GetTileEntity(x, y, z);
@@ -832,15 +649,7 @@ namespace Substrate
             return _tileEntityManager.GetTileEntity(x, y, z);
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Sets a <see cref="TileEntity"/> record for a block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <param name="te">The <see cref="TileEntity"/> to add to the given block.</param>
-        /// <exception cref="ArgumentException">Thrown when the <see cref="TileEntity"/> being passed is of the wrong type for the given block.</exception>
-        /// <exception cref="InvalidOperationException">Thrown when the given block is of a type that does not support a <see cref="TileEntity"/> record.</exception>
         public void SetTileEntity (int x, int y, int z, TileEntity te)
         {
             _tileEntityManager.SetTileEntity(x, y, z, te);
@@ -856,14 +665,7 @@ namespace Substrate
             _dirty = true;
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Creates a default <see cref="TileEntity"/> record suitable for the block at the given local coordinates.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
-        /// <exception cref="InvalidOperationException">Thrown when the given block is of a type that does not support a <see cref="TileEntity"/> record.</exception>
-        /// <exception cref="UnknownTileEntityException">Thrown when the block type requests a <see cref="TileEntity"/> that has not been registered with the <see cref="TileEntityFactory"/>.</exception>
         public void CreateTileEntity (int x, int y, int z)
         {
             _tileEntityManager.CreateTileEntity(x, y, z);
@@ -879,12 +681,7 @@ namespace Substrate
             _dirty = true;
         }
 
-        /// <summary>
+        /// <inheritdoc/>
-        /// Clears any <see cref="TileEntity"/> record set for a block at the givne local coordinates, if one exists.
-        /// </summary>
-        /// <param name="x">Local X-coordinate of a block.</param>
-        /// <param name="y">Local Y-coordinate of a block.</param>
-        /// <param name="z">Local Z-coordinate of a block.</param>
         public void ClearTileEntity (int x, int y, int z)
         {
             _tileEntityManager.ClearTileEntity(x, y, z);
@@ -936,6 +733,263 @@ namespace Substrate
         }
 
 
+        #region Unbounded Container Implementations
+
+        IBlock IBlockCollection.GetBlock (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlock(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        IBlock IBlockCollection.GetBlockRef (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockRef(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IBlockCollection.SetBlock (int x, int y, int z, IBlock block)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlock(x, y, z, block);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        BlockInfo IBlockCollection.GetInfo (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetInfo(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        int IBlockCollection.GetID (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetID(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IBlockCollection.SetID (int x, int y, int z, int id)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetID(x, y, z, id);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        IDataBlock IDataBlockCollection.GetBlock (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlock(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        IDataBlock IDataBlockCollection.GetBlockRef (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockRef(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IDataBlockCollection.SetBlock (int x, int y, int z, IDataBlock block)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlock(x, y, z, block);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        int IDataBlockCollection.GetData (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetData(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IDataBlockCollection.SetData (int x, int y, int z, int data)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetData(x, y, z, data);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        ILitBlock ILitBlockCollection.GetBlock (int x, int y, int z)
+        {
+            throw new NotImplementedException();
+        }
+
+        ILitBlock ILitBlockCollection.GetBlockRef (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockRef(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void ILitBlockCollection.SetBlock (int x, int y, int z, ILitBlock block)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlock(x, y, z, block);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        int ILitBlockCollection.GetBlockLight (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockLight(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void ILitBlockCollection.SetBlockLight (int x, int y, int z, int light)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlockLight(x, y, z, light);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        int ILitBlockCollection.GetSkyLight (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetSkyLight(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void ILitBlockCollection.SetSkyLight (int x, int y, int z, int light)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetSkyLight(x, y, z, light);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        int ILitBlockCollection.GetHeight (int x, int z)
+        {
+            if (x >= 0 && x < _xdim && z >= 0 && z < ZDim) {
+                return GetHeight(x, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : "z");
+        }
+
+        void ILitBlockCollection.SetHeight (int x, int z, int height)
+        {
+            if (x >= 0 && x < _xdim && z >= 0 && z < ZDim) {
+                SetHeight(x, z, height);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : "z");
+        }
+
+        void ILitBlockCollection.UpdateBlockLight (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                UpdateBlockLight(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void ILitBlockCollection.UpdateSkyLight (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                UpdateSkyLight(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        IPropertyBlock IPropertyBlockCollection.GetBlock (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlock(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        IPropertyBlock IPropertyBlockCollection.GetBlockRef (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockRef(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IPropertyBlockCollection.SetBlock (int x, int y, int z, IPropertyBlock block)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlock(x, y, z, block);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        TileEntity IPropertyBlockCollection.GetTileEntity (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetTileEntity(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IPropertyBlockCollection.SetTileEntity (int x, int y, int z, TileEntity te)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetTileEntity(x, y, z, te);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IPropertyBlockCollection.CreateTileEntity (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                CreateTileEntity(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IPropertyBlockCollection.ClearTileEntity (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                ClearTileEntity(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        AlphaBlock IAlphaBlockCollection.GetBlock (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlock(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        AlphaBlockRef IAlphaBlockCollection.GetBlockRef (int x, int y, int z)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                return GetBlockRef(x, y, z);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        void IAlphaBlockCollection.SetBlock (int x, int y, int z, AlphaBlock block)
+        {
+            if (x >= 0 && x < _xdim && y >= 0 && y < _ydim && z >= 0 && z < ZDim) {
+                SetBlock(x, y, z, block);
+            }
+            throw new ArgumentOutOfRangeException(x < 0 || x >= _xdim ? "x" : y < 0 || y >= _ydim ? "y" : "z");
+        }
+
+        #endregion
+
         /*#region IEnumerable<AlphaBlockRef> Members
 
         public IEnumerator<AlphaBlockRef> GetEnumerator ()

Substrate/SubstrateCS/Source/AlphaBlockRef.cs

@@ -140,6 +140,11 @@ namespace Substrate
             _collection.SetTileEntity(_index, te);
         }
 
+        public void CreateTileEntity ()
+        {
+            _collection.CreateTileEntity(_index);
+        }
+
         /// <summary>
         /// Removes any Tile Entity currently attached to the block.
         /// </summary>

Substrate/SubstrateCS/Source/Core/BlockInterface.cs

@@ -107,59 +107,60 @@ namespace Substrate.Core
     /// <summary>
     /// A basic unconstrained container of blocks.
     /// </summary>
+    /// <remarks>The scope of coordinates is undefined for unconstrained block containers.</remarks>
     public interface IBlockCollection
     {
         /// <summary>
         /// Gets a basic block from a block container..
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <returns>A basic <see cref="IBlock"/> from the collection at the given coordinates.</returns>
         IBlock GetBlock (int x, int y, int z);
 
         /// <summary>
         /// Gets a reference object to a basic within a block container.
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <returns>A basic <see cref="IBlock"/> acting as a reference directly into the container at the given coordinates.</returns>
         IBlock GetBlockRef (int x, int y, int z);
 
         /// <summary>
         /// Updates a block in a block container with data from an existing <see cref="IBlock"/> object.
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <param name="block">The <see cref="IBlock"/> to copy basic data from.</param>
         void SetBlock (int x, int y, int z, IBlock block);
 
         /// <summary>
         /// Gets a block's id (type) from a block container.
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <returns>The block id (type) from the block container at the given coordinates.</returns>
         int GetID (int x, int y, int z);
 
         /// <summary>
         /// Sets a block's id (type) within a block container.
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <param name="id">The id (type) to assign to a block at the given coordinates.</param>
         void SetID (int x, int y, int z, int id);
 
         /// <summary>
         /// Gets info and attributes on a block's type within a block container.
         /// </summary>
-        /// <param name="x">The X-coordinate of a block.</param>
+        /// <param name="x">The global X-coordinate of a block.</param>
-        /// <param name="y">The Y-coordinate of a block.</param>
+        /// <param name="y">The global Y-coordinate of a block.</param>
-        /// <param name="z">The Z-coordinate of a block.</param>
+        /// <param name="z">The global Z-coordinate of a block.</param>
         /// <returns>A <see cref="BlockInfo"/> instance for the block's type.</returns>
         BlockInfo GetInfo (int x, int y, int z);
     }
@@ -169,11 +170,85 @@ namespace Substrate.Core
     /// </summary>
     public interface IBoundedBlockCollection : IBlockCollection
     {
+        /// <summary>
+        /// Gets the length of the X-dimension of the container.
+        /// </summary>
         int XDim { get; }
+
+        /// <summary>
+        /// Gets the length of the Y-dimension of the container.
+        /// </summary>
         int YDim { get; }
+
+        /// <summary>
+        /// Gets the length of the Z-dimension of the container.
+        /// </summary>
         int ZDim { get; }
 
+        /// <summary>
+        /// Counts all instances of a block with the given type in the container.
+        /// </summary>
+        /// <param name="id">The id (type) of the block to count.</param>
+        /// <returns>The count of blocks in the container matching the given id (type).</returns>
         int CountByID (int id);
+
+        #region Local Overrides
+
+        /// <summary>
+        /// Gets a basic block from a block container..
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <returns>A basic <see cref="IBlock"/> from the collection at the given coordinates.</returns>
+        new IBlock GetBlock (int x, int y, int z);
+
+        /// <summary>
+        /// Gets a reference object to a basic within a block container.
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <returns>A basic <see cref="IBlock"/> acting as a reference directly into the container at the given coordinates.</returns>
+        new IBlock GetBlockRef (int x, int y, int z);
+
+        /// <summary>
+        /// Updates a block in a block container with data from an existing <see cref="IBlock"/> object.
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <param name="block">The <see cref="IBlock"/> to copy basic data from.</param>
+        new void SetBlock (int x, int y, int z, IBlock block);
+
+        /// <summary>
+        /// Gets a block's id (type) from a block container.
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <returns>The block id (type) from the block container at the given coordinates.</returns>
+        new int GetID (int x, int y, int z);
+
+        /// <summary>
+        /// Sets a block's id (type) within a block container.
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <param name="id">The id (type) to assign to a block at the given coordinates.</param>
+        new void SetID (int x, int y, int z, int id);
+
+        /// <summary>
+        /// Gets info and attributes on a block's type within a block container.
+        /// </summary>
+        /// <param name="x">The container-local X-coordinate of a block.</param>
+        /// <param name="y">The container-local Y-coordinate of a block.</param>
+        /// <param name="z">The container-local Z-coordinate of a block.</param>
+        /// <returns>A <see cref="BlockInfo"/> instance for the block's type.</returns>
+        new BlockInfo GetInfo (int x, int y, int z);
+
+        #endregion
     }
 
     /// <summary>
@@ -195,6 +270,14 @@ namespace Substrate.Core
     /// </summary>
     public interface IBoundedDataBlockCollection : IDataBlockCollection, IBoundedBlockCollection
     {
+        new IDataBlock GetBlock (int x, int y, int z);
+        new IDataBlock GetBlockRef (int x, int y, int z);
+
+        new void SetBlock (int x, int y, int z, IDataBlock block);
+
+        new int GetData (int x, int y, int z);
+        new void SetData (int x, int y, int z, int data);
+
         int CountByData (int id, int data);
     }
 
@@ -228,6 +311,25 @@ namespace Substrate.Core
     /// </summary>
     public interface IBoundedLitBlockCollection : ILitBlockCollection, IBoundedBlockCollection
     {
+        new ILitBlock GetBlock (int x, int y, int z);
+        new ILitBlock GetBlockRef (int x, int y, int z);
+
+        new void SetBlock (int x, int y, int z, ILitBlock block);
+
+        // Local Light
+        new int GetBlockLight (int x, int y, int z);
+        new int GetSkyLight (int x, int y, int z);
+
+        new void SetBlockLight (int x, int y, int z, int light);
+        new void SetSkyLight (int x, int y, int z, int light);
+
+        new int GetHeight (int x, int z);
+        new void SetHeight (int x, int z, int height);
+
+        // Update and propagate light at a single block
+        new void UpdateBlockLight (int x, int y, int z);
+        new void UpdateSkyLight (int x, int y, int z);
+
         // Zero out light in entire collection
         void ResetBlockLight ();
         void ResetSkyLight ();
@@ -267,6 +369,16 @@ namespace Substrate.Core
     /// </summary>
     public interface IBoundedPropertyBlockCollection : IPropertyBlockCollection, IBoundedBlockCollection
     {
+        new IPropertyBlock GetBlock (int x, int y, int z);
+        new IPropertyBlock GetBlockRef (int x, int y, int z);
+
+        new void SetBlock (int x, int y, int z, IPropertyBlock block);
+
+        new TileEntity GetTileEntity (int x, int y, int z);
+        new void SetTileEntity (int x, int y, int z, TileEntity te);
+
+        new void CreateTileEntity (int x, int y, int z);
+        new void ClearTileEntity (int x, int y, int z);
     }
 
     /// <summary>
@@ -285,6 +397,10 @@ namespace Substrate.Core
     /// </summary>
     public interface IBoundedAlphaBlockCollection : IAlphaBlockCollection, IBoundedDataBlockCollection, IBoundedLitBlockCollection, IBoundedPropertyBlockCollection
     {
+        new AlphaBlock GetBlock (int x, int y, int z);
+        new AlphaBlockRef GetBlockRef (int x, int y, int z);
+
+        new void SetBlock (int x, int y, int z, AlphaBlock block);
     }
 
     /// <summary>