tmx

package module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 10, 2025 License: MIT Imports: 15 Imported by: 0

README

tmx

Overview

Go package for parsing Tiled TMX map files.

This is a fork of Noofbiz/tmx, which is licensed under the MIT license.

This fork is also licensed under the MIT License.

Goals of this fork

  • Favor streaming (e.g. change xml.Unmarshal() to xml.NewDecoder().Decode()).
  • Replace TMXURL with something safe to use in a concurrent environment.
  • Add option to skip loading any external files
  • Clean up tmx:"ref" tag <-- is this needed? Just look for LoadRefs on everything?
    • is there a performance impact?
  • Are nested templates allowed? Does this code handle them properly?
  • Build PR to submit back to Noofbiz/tmx

Example Usage

m, err := tmx.ParseFile("test1.tmx")
if err != nil {
  fmt.Println(err)
  return
}
// Do stuff with your tmx map...

Documentation

Index

Constants

View Source
const (
	// HorizontalFlipFlag is a flag for a horizontally flipped tile
	HorizontalFlipFlag uint32 = 0x80000000
	// VerticalFlipFlag is a flag for a vertically flipped tile
	VerticalFlipFlag uint32 = 0x40000000
	// DiagonalFlipFlag is a flag for a diagonally flipped tile
	DiagonalFlipFlag uint32 = 0x20000000
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Chunk

type Chunk struct {
	// X is the x coordinate of the chunk in tiles
	X int `xml:"x,attr"`
	// Y is the y coordinate of the chunk in tiles
	Y int `xml:"y,attr"`
	// Width is the width of the chunk in tiles
	Width int `xml:"width,attr"`
	// Height is the height of the chunk in tiles
	Height int `xml:"height,attr"`
	// Tiles are the tiles in the chunk
	Tiles []TileData `xml:"tile"`
	// Inner is the inner data
	Inner string `xml:",innerxml"`
}

Chunk contains chunk data for a map. A chunk is a set of more than one tile that goes together, so when the map is set to randomly generate, these tiles are generated together.

type Data

type Data struct {
	// Encoding is the encoding used for the data. It can either be "base64"
	// or "csv"
	Encoding string `xml:"encoding,attr"`
	// Compression is the compression used for the data. It can either be
	// "gzip" or "zlib"
	Compression string `xml:"compression,attr,omitempty"`
	// Tiles are the tiles in the data. Not the same as TMXTiles from the Tileset.
	Tiles []TileData `xml:"tile"`
	// Chunks are sets of tiles over an area. Used for randomly generated maps.
	Chunks []Chunk `xml:"chunk"`
	// Inner is the inner data
	Inner string `xml:",innerxml"`
}

Data contains the tile data for a map

func (*Data) UnmarshalXML

func (da *Data) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Ellipse

type Ellipse struct{}

Ellipse is an elliptical shape

type Frame

type Frame struct {
	// TileID is the local id of a tile in the tileset
	TileID uint32 `xml:"tileid,attr"`
	// Duration is how long (in milliseconds) this frame should be displayed
	// before advancing to the next frame
	Duration float64 `xml:"duration,attr"`
}

Frame is an animation frame

type Grid

type Grid struct {
	//  Orientation of the grid for the tiles in this tileset (orthogonal or
	// isometric)
	Orientation string `xml:"orientation,attr"`
	// Width is the width of a grid cell
	Width float64 `xml:"width,attr"`
	// Height is the height of a grid cell
	Height float64 `xml:"height,attr"`
}

Grid is only used in case of isometric orientation, and determines how tile overlays for terrain and collision information are rendered.

type Group

type Group struct {
	// Name is the name of the group layer
	Name string `xml:"name,attr"`
	// OffsetX is the x offset of the group layer in pixels
	OffsetX float64 `xml:"offsetx,attr"`
	// OffsetY is the y offset of the group layer in pixels
	OffsetY float64 `xml:"offsety,attr"`
	// Opacity is the opacity of the layer from 0 to 1
	Opacity float64 `xml:"opacity,attr"`
	// Visible is whether the layer is shown (1) or hidden (0)
	Visible int `xml:"visible,attr"`
	// Properties are the properties of the group
	Properties []Property `xml:"properties>property"`
	// Layers are the layers of the group
	Layers []Layer `xml:"layer"`
	// ObjectGroups are the object groups of the group
	ObjectGroups []ObjectGroup `xml:"objectgroup"`
	// ImageLayers are the image layers of the group
	ImageLayers []ImageLayer `xml:"imagelayer"`
	// Groups are the child groups in the group
	Group []Group `xml:"group"`
}

Group is a root element to organize the layers

func (*Group) UnmarshalXML

func (g *Group) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Image

type Image struct {
	// Format is used for embedded images, in combination with a data child element.
	// Valid values are file extensions like png, gif, jpg, bmp, etc.
	Format string `xml:"format,attr,omitempty"`
	// Source is the reference to the tileset image file.
	Source string `xml:"source,attr"`
	// Transparent defines a specific color that is treated as transparent (example
	// value: “#FF00FF” for magenta). Up until Tiled 0.12, this value is written
	// out without a # but this is planned to change.
	Transparent string `xml:"trans,attr,omitempty"`
	// Width is the image width in pixels
	Width float64 `xml:"width,attr"`
	// Height is the image height in pixels
	Height float64 `xml:"height,attr"`
	// Data is the image data
	Data []Data `xml:"data"`
}

Image is data for an image file

type ImageLayer

type ImageLayer struct {
	// Name is the name of the image layer
	Name string `xml:"name,attr"`
	// OffsetX is the rendering x offset of the image layer in pixels
	OffsetX float64 `xml:"offsetx,attr"`
	// OffsetY is the rendering y offset of the image layer in pixels
	OffsetY float64 `xml:"offsety,attr"`
	// X is the x position of the image layer in pixels
	X float64 `xml:"x,attr"`
	// Y is the y position of the image layer in pixels
	Y float64 `xml:"y,attr"`
	// Opacity is the opacity of the layer from 0 to 1
	Opacity float64 `xml:"opacity,attr"`
	// Visible indicates whether the layer is shown (1) or hidden (0)
	Visible int `xml:"visible,attr"`
	// Properties are the properties of the layer
	Properties []Property `xml:"properties>property"`
	// Images are the images of the layer
	Images []Image `xml:"image"`
}

ImageLayer is a tile layer that contains a reference to an image

func (*ImageLayer) UnmarshalXML

func (i *ImageLayer) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Layer

type Layer struct {
	// Name is the name of the layer
	Name string `xml:"name,attr"`
	// X is the x coordinate of the layer
	X float64 `xml:"x,attr,omitempty"`
	// Y is the y coordinate of the layer
	Y float64 `xml:"y,attr,omitempty"`
	// Width is the width of the layer in tiles. Always the same as the map
	// width for fixed-size maps.
	Width int `xml:"width,attr"`
	// Height is the height of the layer in tiles. Always the same as the map
	// height for fixed-size maps.
	Height int `xml:"height,attr"`
	// Opacity is the opacity of the layer as a value from 0 to 1. Defaults to 1.
	Opacity float64 `xml:"opacity,attr"`
	// Visible is whether the layer is shown(1) or hidden(0). Defaults to 1.
	Visible int `xml:"visible,attr"`
	// OffsetX is the rendering offset for this layer in pixels.
	OffsetX float64 `xml:"offsetx,attr,omitempty"`
	// OffsetY is the rendering offset for this layer in pixels.
	OffsetY float64 `xml:"offsety,attr,omitempty"`
	// Properties are the properties of the layer
	Properties []Property `xml:"properties>property"`
	// Data is any data for the layer
	Data []Data `xml:"data"`
}

Layer is a layer of the map

func (*Layer) UnmarshalXML

func (l *Layer) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Map

type Map struct {
	// Indicate to encoding/xml that the <map> tag should be lowercase.
	XMLName string `xml:"map"`
	// Version is the TMX format version
	Version string `xml:"version,attr,omitempty"`
	// TiledVersion is the Version of Tiled Map Editor used to generate the TMX
	TiledVersion string `xml:"tiledversion,attr,omitempty"`
	// Orientation is the orientation of the map. Tiled supports “orthogonal”,
	// “isometric”, “staggered” and “hexagonal”
	Orientation string `xml:"orientation,attr"`
	// RenderOrder is The order in which tiles on tile layers are rendered.
	// Valid values are right-down (the default), right-up, left-down and left-up.
	// In all cases, the map is drawn row-by-row.
	// (only supported for orthogonal maps at the moment)
	RenderOrder string `xml:"renderorder,attr,omitempty"`
	// Width is the map width in tiles
	Width int `xml:"width,attr"`
	// Height is the map height in tiles
	Height int `xml:"height,attr"`
	// TileWidth is the width of each tile in pixels
	TileWidth int `xml:"tilewidth,attr"`
	// TileHeight is the height of each tile in pixels
	TileHeight int `xml:"tileheight,attr"`
	// HexSideLength determines the width or height (depending on the staggered
	// axis) of the tile’s edge, in pixels. Only for hexagonal maps.
	HexSideLength int `xml:"hexsidelength,attr,omitempty"`
	// StaggerAxis is for staggered and hexagonal maps, determines which axis
	// (“x” or “y”) is staggered.
	StaggerAxis string `xml:"staggeraxis,attr,omitempty"`
	// StaggerIndex is for staggered and hexagonal maps, determines whether the
	// “even” or “odd” indexes along the staggered axis are shifted.
	StaggerIndex string `xml:"staggerindex,attr,omitempty"`
	// BackgroundColor is the background color of the map. Is of the form #AARRGGBB
	BackgroundColor string `xml:"backgroundcolor,attr,omitempty"`
	// NextObjectID stores the next object id available for new objects.
	NextObjectID int `xml:"nextobjectid,attr,omitempty"`
	// Properties are the properties of the map
	Properties []Property `xml:"properties>property"`
	// Tilesets are the tilesets of the map
	Tilesets []Tileset `xml:"tileset"`
	// Layers are the layers of the map
	Layers []Layer `xml:"layer"`
	// ObjectGroups are the object groups of the map
	ObjectGroups []ObjectGroup `xml:"objectgroup"`
	// ImageLayers are the image layers of the map
	ImageLayers []ImageLayer `xml:"imagelayer"`
	// Groups are the groups of the map
	Groups []Group `xml:"group"`
}

Map is the root element of a TMX map

func Parse

func Parse(r io.Reader, tmxPath string, opts ...ParseOpt) (*Map, error)

Parse returns the Map encoded in the reader. Requires the original tmxFile's path in order to load external files correctly.

func ParseFile

func ParseFile(path string, opts ...ParseOpt) (*Map, error)

ParseFile takes the path to a .TMX file and returns the decoded Map.

func (*Map) UnmarshalXML

func (m *Map) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Object

type Object struct {
	// ID is the unique id of the object
	ID uint32 `xml:"id,attr"`
	// Name is the name of the object
	Name string `xml:"name,attr"`
	// Type is the type of the object
	Type string `xml:"type,attr"`
	// X is the x coordinate of the object in pixels
	X float64 `xml:"x,attr"`
	// Y is the y coordinate of the object in pixels
	Y float64 `xml:"y,attr"`
	// Width is the width of the object in pixels
	Width float64 `xml:"width,attr"`
	// Height is the height of the object in pixels
	Height float64 `xml:"height,attr"`
	// Rotation is the rotation of the object in degrees
	Rotation float64 `xml:"rotation,attr"`
	// GID is a reference to the tile
	GID uint32 `xml:"gid,attr"`
	// Visible is whether the object is shown (1) or hidden (0)
	Visible int `xml:"visible,attr"`
	// Template is a reference to a template file
	Template string `xml:"template,attr" tmx:"ref"`
	// Properties are the properties of the object
	Properties []Property `xml:"properties>property"`
	// Ellipses are any elliptical shapes
	Ellipses []Ellipse `xml:"ellipse"`
	// Polygons are any polygon shapes
	Polygons []Polygon `xml:"polygon"`
	// Polylines are any poly line shapes
	Polylines []Polyline `xml:"polyline"`
	// Text is any text
	Text []Text `xml:"text"`
	// Images is any image in the object
	Images []Image `xml:"image"`
}

Object is used to add custom information to a map, such as a spawn point

func (*Object) LoadRefs

func (o *Object) LoadRefs(dir string) error

LoadRefs is the RefLoader implementation to load external tileset files.

func (*Object) UnmarshalXML

func (o *Object) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type ObjectGroup

type ObjectGroup struct {
	// Name is the name of the object group
	Name string `xml:"name,attr"`
	// Color is the color used to display the objects in this group
	Color string `xml:"color,attr"`
	// X is the x coordinate of the object group in tiles
	X int `xml:"x,attr"`
	// Y is the y coordinate of the object group in tiles
	Y int `xml:"y,attr"`
	// Width is the width of the object group in tiles. Meaningless.
	Width int `xml:"width,attr"`
	// Opacity is the opacity of the layer from 0 to 1.
	Opacity float64 `xml:"opacity,attr"`
	// Visible is whether the layer is shown (1) or hidden (0).
	Visible int `xml:"visible,attr"`
	// OffsetX is the rendering x offset for this object group in pixels.
	OffsetX float64 `xml:"offsetx,attr"`
	// OffsetY is the rendering y offset for this object group in pixels.
	OffsetY float64 `xml:"offsety,attr"`
	// DrawOrder is whether the objects are drawn according to the order of
	// appearance ("index") or sorted by their y-coordinate ("topdown")
	DrawOrder string `xml:"draworder,attr"`
	// Properties are the properties of the object layer
	Properties []Property `xml:"properties>property"`
	// Objects are the objects in the object layer
	Objects []Object `xml:"object"`
}

ObjectGroup is a group of objects

func (*ObjectGroup) UnmarshalXML

func (o *ObjectGroup) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type ParseOpt added in v0.3.2

type ParseOpt interface {
	String() string
	// contains filtered or unexported methods
}

func IgnoreRefs added in v0.3.2

func IgnoreRefs() ParseOpt

type Point

type Point struct{}

Point is a single point located at the object's position

type Polygon

type Polygon struct {
	// Points are a list of x,y coordinates in pixels
	Points string `xml:"points,attr"`
}

Polygon is a polygon shape

type Polyline

type Polyline struct {
	// Points are a list of x,y coordinates in pixels
	Points string `xml:"points,attr"`
}

Polyline is a polygon that doesn't have to close

type Property

type Property struct {
	// Name is the name of the property
	Name string `xml:"name,attr"`
	// Type is the type of the property. It can be string, int, float, bool,
	// color or file
	Type string `xml:"type,attr"`
	// Value is the value of the property
	Value string `xml:"value,attr"`
}

Property is any custom data added to elements of the map

func (*Property) UnmarshalXML

func (p *Property) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type RefLoader

type RefLoader interface {
	LoadRefs(dir string) error
}

RefLoader is an interface for loading references to other files

type Template

type Template struct {
	// Tilesets are the tilesets for the template
	Tilesets []Tileset `xml:"tileset"`
	// Objects are the template objects
	Objects []Object `xml:"object"`
}

Template is a separate file that contains the template root element, a map object and a tileset element that points to an external tileset if the object is a tile object

type Terrain

type Terrain struct {
	// Name is the name of the terrain type
	Name string `xml:"name,attr"`
	// Tile is the id of the local tile that represents the terrain
	Tile uint32 `xml:"tile,attr"`
}

Terrain is a terrain

type Text

type Text struct {
	// FontFamily is the font family used
	FontFamily string `xml:"fontfamily,attr"`
	// PixelSize is the size of the font in pixels
	PixelSize float64 `xml:"pixelsize,attr"`
	// Wrap is whether word wrapping is enabled (1) or disabled (0)
	Wrap int `xml:"wrap,attr"`
	// Color is the color of the text in #AARRGGBB or #RRGGBB format
	Color string `xml:"color,attr"`
	// Bold is whether the font is bold (1) or not (0)
	Bold int `xml:"bold,attr"`
	// Italic is whether the font is italic (1) or not (0)
	Italic int `xml:"italic,attr"`
	// Underline is whether a line should be drawn below the text (1) or not (0)
	Underline int `xml:"underline,attr"`
	// Strikeout is whether a line should be drawn through the text (1) or not (0)
	Strikeout int `xml:"strikeout,attr"`
	// Kerning is whether kerning should be used while rendering the text (1) or
	// not (0)
	Kerning int `xml:"kerning,attr"`
	// Halign is the horizontal alignment of the text within the object (left,
	// center or right)
	Halign string `xml:"halign,attr"`
	// Valign is the vertical alignment of the text within the object (top,
	// center or bottom)
	Valign string `xml:"valign,attr"`
	// CharData is the character data of the text element
	CharData string `xml:",chardata"`
}

Text is a text object

func (*Text) UnmarshalXML

func (t *Text) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the encoding/xml Unmarshaler interface

type Tile

type Tile struct {
	// ID is the local tile id within its tileset
	ID uint32 `xml:"id,attr"`
	// Type is the type of the tile
	Type string `xml:"type,attr"`
	// Terrain defines the terrain type of each corner of the tile, given as
	// comma-separated indexes in the terrain types array in the order top-left,
	// top-right, bottom-left, bottom-right. Leaving out a value means that corner
	// has no terrain. (optional)
	Terrain string `xml:"terrain,attr"`
	// Probability is a percentage indicating the probability that this tile is
	// chosen when it competes with others while editing with the terrain tool.
	Probability float64 `xml:"probability,attr"`
	// Properties are the custom properties of the tile
	Properties []Property `xml:"properties>property"`
	// Image is the image associated with the tile
	Image []Image `xml:"image"`
	// ObjectGroups are a group of objects
	ObjectGroup []ObjectGroup `xml:"objectgroup"`
	// AnimationFrames are any frames to animate the tile
	AnimationFrames []Frame `xml:"animation>frame"`
}

Tile is a single tile in a tile set

type TileData

type TileData struct {
	// RawGID is the global tile ID given in the map
	RawGID uint32 `xml:"gid,attr"`
	// GID is the global tile ID with the flipping bits removed
	GID uint32
	// Flipping is the flipping flags present
	// You can & this with the constants HorizontalFlipFlag, VerticalFlipFlag, and
	// DiagonalFlipFlag to find out if the flag was present on the tile.
	Flipping uint32
}

TileData contains the gid that maps a tile to the sprite

type TileOffset

type TileOffset struct {
	// X is the horizontal offset in pixels
	X float64 `xml:"x,attr"`
	// Y is the vertical offset in pixels. Positive is down.
	Y float64 `xml:"y,attr"`
}

TileOffset is used to specify an offset in pixels, to be applied when drawing a tile from the related tileset. When not present, no offset is applied.

type Tileset

type Tileset struct {
	// FirstGID is  the first global tile ID of this tileset (this global ID maps
	// to the first tile in this tileset)
	FirstGID uint32 `xml:"firstgid,attr"`
	// Source is the location of the external tilemap TSX file, if any
	Source string `xml:"source,attr,omitempty" tmx:"ref"`
	// Name is the name of the tileset
	Name string `xml:"name,attr"`
	// TileWidth is the (maximum) width of tiles in the tileset
	TileWidth int `xml:"tilewidth,attr"`
	// TileHeight is the (maximum) height of the tiles in the tileset
	TileHeight int `xml:"tileheight,attr"`
	// Spacing is the spacing of the tiles in pixels between the tiles in the tileset
	Spacing int `xml:"spacing,attr,omitempty"`
	// Margin is the margin around the tiles in pixels of the tiles in the tileset
	Margin float64 `xml:"margin,attr,omitempty"`
	// TileCount is the number of tiles in the tileset
	TileCount int `xml:"tilecount,attr,omitempty"`
	// Columns is the number of tile columns in the tileset
	Columns int `xml:"columns,attr,omitempty"`
	// TileOffset is used to specify an offset in pixels, to be applied when
	// drawing a tile from the related tileset. When not present, no offset
	// is applied
	TileOffset []TileOffset `xml:"tileoffset"`
	// Grid is is only used in case of isometric orientation, and determines how
	// tile overlays for terrain and collision information are rendered
	Grid []Grid `xml:"grid"`
	// Properties are the custom properties of the tileset
	Properties []Property `xml:"properties>property"`
	// Image is the image associated with the tileset
	Image []Image `xml:"image"`
	// TerrainTypes are the terraintypes associated with the tileset
	TerrainTypes []Terrain `xml:"terraintypes>terrain"`
	// Tiles are tiles in the tileset
	Tiles []Tile `xml:"tile"`
	// WangSets contain the list of wang sets defined for this tileset
	WangSets []WangSet `xml:"wangsets>wangset"`
}

Tileset is a tileset used for the map

func (*Tileset) LoadRefs

func (t *Tileset) LoadRefs(dir string) error

LoadRefs is the RefLoader implementation to load external tileset files.

type WangCornerColor

type WangCornerColor struct {
	// Name is the name of this color
	Name string `xml:"name,attr"`
	// Color is the color in #RRGGBB format
	Color string `xml:"color,attr"`
	// Tile is the tile ID of the tile representing this color
	Tile uint32 `xml:"tile,attr"`
	// Probability is the relative probability that this color is chosen
	Probability float64 `xml:"probability,attr"`
}

WangCornerColor is a color that can be used to define the edge of a Wang tile

type WangEdgeColor

type WangEdgeColor struct {
	// Name is the name of this color
	Name string `xml:"name,attr"`
	// Color is the color in #RRGGBB format
	Color string `xml:"color,attr"`
	// Tile is the tile ID of the tile representing this color
	Tile uint32 `xml:"tile,attr"`
	// Probability is the relative probability that this color is chosen
	Probability float64 `xml:"probability,attr"`
}

WangEdgeColor is a color that can be used to define the edge of a Wang tile

type WangSet

type WangSet struct {
	// Name is the name of the wang set
	Name string `xml:"name,attr"`
	// Tile is the local tile id of the wang set
	Tile uint32 `xml:"id,attr"`
	// WangCornerColor is a color that can be used to define the corner of a
	// Wang tile
	WangCornerColors []WangCornerColor `xml:"wangcornercolor"`
	// WangEdgeColor is a color that can be used to define the edge of a Wang tile
	WangEdgeColors []WangEdgeColor `xml:"wangedgecolor"`
	// WangTile defines a Wang Tile
	WangTiles []WangTile `xml:"wangtile"`
}

WangSet is a wang set from the TMX map

type WangTile

type WangTile struct {
	// TileID is the tile ID
	TileID uint32 `xml:"tileid,attr"`
	// WangID is a 32-bit unsigned integer stored in the format 0xCECECECE where
	// C is a corner color and each E is an edge color, from right to left
	// clockwise, starting with the top edge.
	// It's stored as a string here rather than a uint32 it's easer for the end
	// user of the library to read / parse themselves.
	WangID string `xml:"wangid,attr"`
}

WangTile is a wang tile. It refers to a tile in the tileset and associates it with a Wang ID

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL