Where's the documentation?

Feb 17, 2011 at 12:10 AM

I have no idea how to get started using this because I can't find any decent documentation for it. I can get it to render a map by following the tutorial, but I can't find anywhere that explains the xTile engine's methods or how to use them. How do I access tile properties? How do I tell which tiles are currently rendered within the viewport? How do I access current tile coordinates from map tile coordinates? All these things are necessary for something other than "scroll across map with no interaction".


Something else I can't quite figure out: the layers in the demo map in the background scroll at different rates. It seems to do this by default because there's nothing in the code side that's doing it (unless it's built into the engine). How do I control this?




Feb 17, 2011 at 7:02 AM

You are right, other than the tutorial and browsing through the XML comments (if you download the source), there is very limited documentation. I will try to compile and publish a few notes, which I can hopefully turn into a manual of sorts.

In the meantime I'll try to answer some of your questions:

Tile Properties

Assuming you have a Tile instance, say in a variable tile, you can access properties as follows:

int propertyValue = tile.Properties["PropertyKey"] ;

Depending on the destination type specified (int, float, bool and string supported - int the in the example above), the API will automatically cast to the required type through implicit casting implemented within the engine. See this discussion for further details: http://tide.codeplex.com/discussions/244983

Which tiles are rendered within the viewport

This certainly justifies some explaining.. First of all, the viewport is relative to the size of the whole map, which in turn is defined to be the largest width and the largest height (in pixels) of the layers present in the map. These width and height values usually correspond to one particular layer in the map, but it is possible to have one layer whose width is largest, and a different layer whose height is largest, although this would make for some very weird parallax effects! Actually, the most natural map configuration would be one in which the layers increase in size (both width and height).

To get back to the point, the viewport pixel coordinates are based on the overall dimensions of the map as described above, and that usually means that the largest layer (usually the foreground layer used for gameplay) has a one-to-one correspondence with the viewport. To illustrate an example, let's say you have a 2 layer map, each using tiles of size 32x32 pixels, where the background layer is 100 x 50 tiles, and the foreground is 200 x 100. Then a viewport with position 70, 40 and dimensions 320 x 160 pixels  would display the foreground tiles starting from tile [2, 1] at the topleft and extending to 10 x 5 tiles across and down.

As for the background (or any other layer for that matter), these are positioned in relative scale to the map size, meaning for instance, that if the background layer is half the size of the foreground, then it will appear to scroll at half the speed, to create in effect, the illusion of parallax. The computation is actually not simply a ratio of scale - it also take the viewport dimensions into account, and the reason for this is to ensure, that when the viewport reaches a right or bottom edge of the primary layer, all other layers align with this edge precisely - without this correction, the alignment would only occur when the viewport leaves the map entirely.

Anyhow.. this gets me back to the question of scroll speeds, and basically the answer is that the engine controls the scroll speed based on relative layer size and viewport size.

As for processing the contents of the map, once the primary layer is determined, it is possible to invoke the layer's GetTileLocation method to convert from pixels (absolute layer coords in pixels) to tile coordinate. See this discussion for more details: http://tide.codeplex.com/discussions/230179

I hope that helps!

Feb 17, 2011 at 7:09 AM

Amazing! Thanks for the explainations. Your engine/editor really is the only viable one for XNA that fits my needs and will hopefully make getting my project off the ground much easier.



Feb 17, 2011 at 8:00 AM

Oh, one more problem I'm not clear on (this is probably due to my inexperience working with C#). In the code example you linked to, you use "Tile currentTile = playerLayer.Tiles[tileLocation];" to store a reference to a tile. When I attempt to do this I get build errors because Tile is not a valid namespace. Is this an error in my setup of xTile or am I missing something?



Feb 17, 2011 at 8:36 AM
Edited Feb 17, 2011 at 8:38 AM

You might be missing a using clause at the top of your source code. To be on the safe side, I suggest you include all the following:


using xTile;
using xTile.Dimensions;

using xTile.Display;

using xTile.Layers;

using xTile.Tiles;


You could also add the following but you will probably never use them directly:


using xTile.Format;

using xTile.ObjectModel;

using xTile.Pipeline;

using xTile.Properties;
Feb 17, 2011 at 9:19 AM

Yeah, I figured that out a few minutes before you replied. Thanks though!

I've run into another problem that I can't quite figure out. I'm trying to access a tile's properties using the method you describe in your other post. Here is my code:

// Loop through tiles currently visible on screen, check if they're solid
                for (int y = tileStartY; y <= tileEndY; y++)
                    for (int x = tileStartX; x <= tileEndX; x++)
                        int tileX = ((x * tileSize) + 10) - viewport.X;
                        int tileY = ((y * tileSize) + 10) - viewport.Y;
                        // check tile properties
                        Tile currentTile = foreground.Tiles[x, y];
                        if (currentTile.Properties["isSolid"] == true)
                            //Do stuff

When I try to compile, I get a "Object reference not set to an instance of an object." error on the line "if (currentTile.Properties["isSolid"] == true)"

Any idea what could cause that? I can't figure it out.


Feb 17, 2011 at 11:23 AM

Unless all the tiles in your layer are set, I think you need to add a check to verify that "currentTile" is not null before attempting to reference "Properties". Something like the following should do:

if (currentTile != null && currentTile.Properties["isSolid"] == true)
    //Do stuff

It tIDE it is possible to have null tiles, unlike in other map editors that require you to specify a special blank tile (usually index 0). The downside of this is that you need to check if a tile is null before processing it. On the plus side, you don't need to reserve an empty tile in your tile sheet image and the tile engine is spared from needlessly rendering transparent tiles.