tmx

README

tmx

A parser for the TMX file format, used in the Tiled Map Editor.

Installation

go get -u github.com/fardog/tmx

Version Compatibility

This library has no dependencies outside of the Go standard library, and is tested on Go 1.7 and above. It does not yet respect any versioning standards, so you are encouraged to vendor it in your projects to ensure compatibility.

TODO/Help Wanted

• CSV data formats are untested and use a custom parser
• Test Coverage is very poor

License

MIT. See LICENSE for details.

Documentation

Overview

Package tmx implements a parser for the TMX file format used in the Tiled Map Editor.

Index

• Constants
• Variables
• type Data
  • func (d *Data) Bytes() ([]byte, error)
• type Frame
• type GlobalID
  • func (g GlobalID) BareID() uint32
  • func (g GlobalID) IsFlippedDiagonally() bool
  • func (g GlobalID) IsFlippedHorizontally() bool
  • func (g GlobalID) IsFlippedVertically() bool
  • func (g GlobalID) TileID(t *TileSet) TileID
• type Image
• type ImageLayer
• type Layer
  • func (l *Layer) TileDefs(tss []TileSet) (tds []*TileDef, err error)
  • func (l *Layer) TileGlobalRefs() ([]TileGlobalRef, error)
• type Map
  • func Decode(r io.Reader) (*Map, error)
  • func (m *Map) LayerWithName(name string) *Layer
  • func (m *Map) ObjectGroupWithName(name string) *ObjectGroup
  • func (m *Map) TileSetWithName(name string) *TileSet
• type Object
  • func (o *Object) Ellipse() bool
• type ObjectGroup
• type ObjectID
• type Objects
  • func (ol Objects) WithName(name string) *Object
• type Point
• type Poly
  • func (p *Poly) Points() (pts []Point, err error)
• type Properties
  • func (pl Properties) Bool(name string) (v bool, err error)
  • func (pl Properties) Float(name string) (v float64, err error)
  • func (pl Properties) Int(name string) (v int64, err error)
  • func (pl Properties) WithName(name string) *Property
• type Property
• type Tag
• type Terrain
• type TerrainType
• type Tile
  • func (t *Tile) TerrainType() (*TerrainType, error)
• type TileDef
• type TileGlobalRef
• type TileID
• type TileOffset
• type TileSet
  • func DecodeTileset(r io.Reader) (*TileSet, error)
  • func (t *TileSet) TileWithID(id TileID) *Tile

Constants

const (
	TileFlippedHorizontally = 0x80000000
	TileFlippedVertically   = 0x40000000
	TileFlippedDiagonally   = 0x20000000
	TileFlipped             = TileFlippedHorizontally | TileFlippedVertically | TileFlippedDiagonally
)

Bitmasks for tile orientation

Variables

var (
	ErrUnsupportedEncoding      = errors.New("invalid encoding")
	ErrUnsupportedCompression   = errors.New("unsupported compression type")
	ErrNoSuitableTileSet        = errors.New("no suitable tileset found for tiles")
	ErrPropertyNotFound         = errors.New("no property with a given name was found")
	ErrPropertyWrongType        = errors.New("a property was found, but its type was incorrect")
	ErrPropertyFailedConversion = errors.New("the property failed to convert to the expected type")
)

Possible Errors

Types

type Data

type Data struct {
	Encoding       string          `xml:"encoding,attr"`
	Compression    string          `xml:"compression,attr"`
	TileGlobalRefs []TileGlobalRef `xml:"tile"`

	// Raw Data loaded from XML. Not intended to be used directly; use the
	// methods on this struct to accessed parsed data.
	RawBytes []byte `xml:",innerxml"`
}

Data represents a payload in a given object; it may be specified in several different encodings and compressions, or as a straight datastructure containing TileGlobalRefs

func (*Data) Bytes

func (d *Data) Bytes() ([]byte, error)

Bytes returns the byte array in the Data object, after being uncompressed and decoded. In the case of a non-encoded payload, returning a zero-length array is completely valid.

While you may use this function, it is typically expected to be called by other internal functions when generating a tile list. However, it is safe to be called by users of this library if desired, so is exported.

type Frame

type Frame struct {
	TileID       TileID `xml:"tileid,attr"`
	DurationMsec int    `xml:"duration,attr"`
}

Frame is a frame specifier in a given Animation

type GlobalID

type GlobalID uint32

GlobalID is a per-map global unique ID used in Layer tile definitions (TileGlobalRef). It also encodes how the tile is drawn; if it's mirrored across an axis, for instance. Typically, you will not use a GlobalID directly; it will be mapped for you by various helper methods on other structs.

func (GlobalID) BareID

func (g GlobalID) BareID() uint32

BareID returns the actual integer ID without tile flip information

func (GlobalID) IsFlippedDiagonally

func (g GlobalID) IsFlippedDiagonally() bool

IsFlippedDiagonally returns true if the ID specifies a diagonal flip

func (GlobalID) IsFlippedHorizontally

func (g GlobalID) IsFlippedHorizontally() bool

IsFlippedHorizontally returns true if the ID specifies a horizontal flip

func (GlobalID) IsFlippedVertically

func (g GlobalID) IsFlippedVertically() bool

IsFlippedVertically returns true if the ID specifies a vertical flip

func (GlobalID) TileID

func (g GlobalID) TileID(t *TileSet) TileID

TileID returns the TileSet-relative TileID for a given GlobalID

type Image

type Image struct {
	Format           string   `xml:"format,attr"`
	ObjectID         ObjectID `xml:"id,attr"`
	Source           string   `xml:"source,attr"`
	TransparentColor string   `xml:"trans,attr"`
	Width            int      `xml:"width,attr"`
	Height           int      `xml:"height,attr"`
	Data             Data     `xml:"data"`
}

Image represents a graphic asset to be used for a TileSet (or other element). While maps created with the Tiled editor may not have the image embedded, the format can support it; no additional decoding or loading is attempted by this library, but the data will be available in the struct.

type ImageLayer

type ImageLayer struct {
	Name       string     `xml:"name,attr"`
	OffsetX    int        `xml:"offsetx,attr"`
	OffsetY    int        `xml:"offsety,attr"`
	X          int        `xml:"x,attr"`
	Y          int        `xml:"y,attr"`
	Width      int        `xml:"width,attr"`
	Height     int        `xml:"height,attr"`
	Opacity    float32    `xml:"opacity,attr"`
	Visible    bool       `xml:"visible,attr"`
	Properties Properties `xml:"properties>property"`
	Image      Image      `xml:"image"`
}

ImageLayer is a layer consisting of a single image, such as a background.

type Layer

type Layer struct {
	Name       string     `xml:"name,attr"`
	X          int        `xml:"x,attr"`
	Y          int        `xml:"y,attr"`
	Width      int        `xml:"width,attr"`
	Height     int        `xml:"height,attr"`
	Opacity    float32    `xml:"opacity,attr"`
	Visible    bool       `xml:"visible,attr"`
	OffsetX    int        `xml:"offsetx,attr"`
	OffsetY    int        `xml:"offsety,attr"`
	Properties Properties `xml:"properties>property"`

	// Raw Data loaded from XML. Not intended to be used directly; use the
	// methods on this struct to accessed parsed data.
	RawData Data `xml:"data"`
	// contains filtered or unexported fields
}

Layer specifies a layer of a given Map; a Layer contains tile arrangement information.

func (*Layer) TileDefs

func (l *Layer) TileDefs(tss []TileSet) (tds []*TileDef, err error)

TileDefs gets the definitions for all the tiles in a given Layer, matched with the given TileSets

func (*Layer) TileGlobalRefs

func (l *Layer) TileGlobalRefs() ([]TileGlobalRef, error)

TileGlobalRefs retrieves tile reference data from the layer, after processing the raw tile data

type Map

type Map struct {
	Version         string        `xml:"version,attr"`
	Orientation     string        `xml:"orientation,attr"`
	RenderOrder     string        `xml:"renderorder,attr"`
	Width           int           `xml:"width,attr"`
	Height          int           `xml:"height,attr"`
	TileWidth       int           `xml:"tilewidth,attr"`
	TileHeight      int           `xml:"tileheight,attr"`
	HexSideLength   int           `xml:"hexsidelength,attr"`
	StaggerAxis     rune          `xml:"staggeraxis,attr"`
	StaggerIndex    string        `xml:"staggerindex,attr"`
	BackgroundColor string        `xml:"backgroundcolor,attr"`
	NextObjectID    ObjectID      `xml:"nextobjectid,attr"`
	TileSets        []TileSet     `xml:"tileset"`
	Properties      Properties    `xml:"properties>property"`
	Layers          []Layer       `xml:"layer"`
	ObjectGroups    []ObjectGroup `xml:"objectgroup"`
	ImageLayers     []ImageLayer  `xml:"imagelayer"`
}

Map represents a Tiled map, and is the top-level container for the map data

func Decode

func Decode(r io.Reader) (*Map, error)

Decode takes a reader for an XML file, and returns a new Map decoded from that XML.

func (*Map) LayerWithName

func (m *Map) LayerWithName(name string) *Layer

LayerWithName retrieves the first Layer matching the provided name. Returns `nil` if not found.

func (*Map) ObjectGroupWithName

func (m *Map) ObjectGroupWithName(name string) *ObjectGroup

ObjectGroupWithName retrieves the first ObjectGroup matching the provided name. Returns `nil` if not found.

func (*Map) TileSetWithName

func (m *Map) TileSetWithName(name string) *TileSet

TileSetWithName retrieves the first TileSet matching the provided name. Returns `nil` if not found.

type Object

type Object struct {
	ObjectID   ObjectID   `xml:"id,attr"`
	Name       string     `xml:"name,attr"`
	Type       string     `xml:"type,attr"`
	X          float64    `xml:"x,attr"`
	Y          float64    `xml:"y,attr"`
	Width      float64    `xml:"width,attr"`
	Height     float64    `xml:"height,attr"`
	Rotation   int        `xml:"rotation,attr"`
	GlobalID   GlobalID   `xml:"gid,attr"`
	Visible    bool       `xml:"visible,attr"`
	Properties Properties `xml:"properties>property"`
	Polygons   []Poly     `xml:"polygon"`
	Polylines  []Poly     `xml:"polyline"`
	Image      Image      `xml:"image"`

	// Raw Extras loaded from XML. Not intended to be used directly; use the
	// methods on this struct to accessed parsed data.
	RawExtra []Tag `xml:",any"`
}

Object is an individual object, such as a Polygon, Polyline, or otherwise.

func (*Object) Ellipse

func (o *Object) Ellipse() bool

Ellipse returns true if the object is an ellipse, else false

type ObjectGroup

type ObjectGroup struct {
	Name       string     `xml:"name,attr"`
	Color      string     `xml:"color,attr"`
	X          int        `xml:"x,attr"`
	Y          int        `xml:"y,attr"`
	Width      int        `xml:"width,attr"`
	Height     int        `xml:"height,attr"`
	Opacity    float32    `xml:"opacity,attr"`
	Visible    bool       `xml:"visible,attr"`
	OffsetX    int        `xml:"offsetx,attr"`
	OffsetY    int        `xml:"offsety,attr"`
	DrawOrder  string     `xml:"draworder,attr"`
	Properties Properties `xml:"properties>property"`
	Objects    Objects    `xml:"object"`
}

ObjectGroup is a group of objects within a Map or tile, used to specify sub-objects such as polygons.

type ObjectID

type ObjectID int32

ObjectID specifies a unique ID

type Objects

type Objects []Object

Objects is an array of Object

func (Objects) WithName

func (ol Objects) WithName(name string) *Object

WithName retrieves the first object with a given name, nil if none

type Point

type Point struct {
	X, Y int
}

Point is an X, Y coordinate in space

type Poly

type Poly struct {
	// Raw Points loaded from XML. Not intended to be used directly; use the
	// methods on this struct to accessed parsed data.
	RawPoints string `xml:"points,attr"`
}

Poly represents a collection of points; used to represent a Polyline or a polygon

func (*Poly) Points

func (p *Poly) Points() (pts []Point, err error)

Points returns a list of points in a Poly

type Properties

type Properties []Property

Properties is an array of Property objects

func (Properties) Bool

func (pl Properties) Bool(name string) (v bool, err error)

Bool returns a value from a given boolean property

func (Properties) Float

func (pl Properties) Float(name string) (v float64, err error)

Float returns a value from a given float property

func (Properties) Int

func (pl Properties) Int(name string) (v int64, err error)

Int returns a value from a given integer property

func (Properties) WithName

func (pl Properties) WithName(name string) *Property

WithName returns the first property in a list with a given name, nil if none

type Property

type Property struct {
	Name  string `xml:"name,attr"`
	Type  string `xml:"type,attr"`
	Value string `xml:"value,attr"`
}

Property wraps any number of custom properties, and is used as a child of a number of other objects.

type Tag

type Tag struct {
	XMLName xml.Name
	Content string `xml:",innerxml"`
}

Tag represents a bare XML tag; it is used to decode some not-attribute-nor- data-having properties of other objects, and is not intended for direct use.

type Terrain

type Terrain struct {
	Name       string     `xml:"name,attr"`
	TileID     TileID     `xml:"tile,attr"`
	Properties Properties `xml:"properties>property"`
}

Terrain defines a type of terrain and its associated tile ID.

type TerrainType

type TerrainType struct {
	TopLeft     TileID
	TopRight    TileID
	BottomLeft  TileID
	BottomRight TileID
}

TerrainType represents the unique corner tiles used by a particular terrain

type Tile

type Tile struct {
	TileID      TileID      `xml:"id,attr"`
	Probability float32     `xml:"probability,attr"`
	Properties  Properties  `xml:"properties>property"`
	Image       Image       `xml:"image"`
	Animation   []Frame     `xml:"animation>frame"`
	ObjectGroup ObjectGroup `xml:"objectgroup"`

	// Raw TerrainType loaded from XML. Not intended to be used directly; use
	// the methods on this struct to accessed parsed data.
	RawTerrainType string `xml:"terrain,attr"`
	// contains filtered or unexported fields
}

Tile represents an individual tile within a TileSet

func (*Tile) TerrainType

func (t *Tile) TerrainType() (*TerrainType, error)

TerrainType returns a TerrainType objects from the given Tile

type TileDef

type TileDef struct {
	Nil                 bool
	ID                  TileID
	GlobalID            GlobalID
	TileSet             *TileSet
	Tile                *Tile
	HorizontallyFlipped bool
	VerticallyFlipped   bool
	DiagonallyFlipped   bool
}

TileDef is a representation of an individual hydrated tile, with all the necessary data to render that tile; it's built up off of the tile GlobalIDs, to give a layer-local TileID, its properties, and the tileset used to render it (as a reference).

type TileGlobalRef

type TileGlobalRef struct {
	GlobalID GlobalID `xml:"gid,attr"`
}

TileGlobalRef is a reference to a tile GlobalID

type TileID

type TileID uint32

TileID is a tile id unique to each TileSet; often called the "local tile ID" in the Tiled docs.

type TileOffset

type TileOffset struct {
	X int `xml:"x,attr"`
	Y int `xml:"y,attr"`
}

TileOffset is used to specify an offset in pixels to be applied when drawing a tile from the related TileSet

type TileSet

type TileSet struct {
	FirstGlobalID GlobalID   `xml:"firstgid,attr"`
	Source        string     `xml:"source,attr"`
	Name          string     `xml:"name,attr"`
	TileWidth     int        `xml:"tilewidth,attr"`
	TileHeight    int        `xml:"tileheight,attr"`
	Spacing       int        `xml:"spacing,attr"`
	Margin        int        `xml:"margin,attr"`
	TileCount     int        `xml:"tilecount,attr"`
	Columns       int        `xml:"columns,attr"`
	Properties    Properties `xml:"properties>property"`
	TileOffset    TileOffset `xml:"tileoffset"`
	Image         Image      `xml:"image"`
	TerrainTypes  []Terrain  `xml:"terraintypes>terrain"`
	Tiles         []Tile     `xml:"tile"`
}

TileSet is a set of tiles, including the graphics data to be mapped to the tiles, and the actual arrangement of tiles.

func DecodeTileset

func DecodeTileset(r io.Reader) (*TileSet, error)

Same as Decode, but for TSX files

func (*TileSet) TileWithID

func (t *TileSet) TileWithID(id TileID) *Tile

TileWithID returns a pointer to the Tile with a given TileID; nil if one is not found.