tmx

package
Version: v0.0.0-...-793ea6c Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2021 License: BSD-3-Clause Imports: 20 Imported by: 2

Documentation

Overview

Package tmx implements routines for rendering tmx maps.

It loads a 2D tmx map into a few meshes stored in a *gfx.Object and applies textures such that it would render properly.

At present the package only supports orthogonal tile map rendering, and has some issues with proper ordering of perspective (I.e. non-uniformly sized) tiles (see for instance tiled-qt/examples/perspective_walls.tmx).

Package tmx implements a Tiled Map XML file loader.

The Tiled Map XML file specification can be found at:

https://github.com/bjorn/tiled/wiki/TMX-Map-Format

This package supports all of the current file specification with the exception of embedded image data (I.e. non-external tileset images).

Index

Constants

View Source
const (
	// Flags representing horizontal, vertical, and diagonal tile flipping.
	// These can be used in combination with gid's, like so:
	//
	// if (gid & FLIPPED_HORIZONTALLY_FLAG) > 0 {
	//     ...draw the tiled flipped horizontally...
	// }
	FLIPPED_HORIZONTALLY_FLAG uint32 = 0x80000000
	FLIPPED_VERTICALLY_FLAG   uint32 = 0x40000000
	FLIPPED_DIAGONALLY_FLAG   uint32 = 0x20000000
)

Variables

View Source
var (
	// Error representing an unknown encoding method inside of a tmx file
	ErrBadEncoding = errors.New("tile data encoding type is not supported")

	// Error representing an unknown compression method inside of a tmx file
	ErrBadCompression = errors.New("tile data compression type is not supported")
)
View Source
var (
	Shader *gfx.Shader
)

Functions

func Load

func Load(m *Map, c *Config, tsImages map[string]*image.RGBA) (layers map[string]map[string]*gfx.Object)

Load loads the given tmx map, m, and returns a slice of *gfx.Object with the proper meshes and textures attached to them.

If the configuration, c, is non-nil then it is used in place of the default configuration.

The tsImages map should be a map of tileset image filenames and their associated loaded RGBA images. Tiles who reference tilesets who are not found in the map will be omited (not rendered) in the returned objects.

Types

type Config

type Config struct {
	// The value which is used to offset each layer on the Y axis.
	LayerOffset float64

	// The value to offset each individual tile from one another on the Y axis.
	TileOffset float64
}

Config represents a tmx mesh configuration

type Coord

type Coord struct {
	X, Y int
}

Coord represents a single 2D coordinate pair (x, y)

type Ellipse

type Ellipse struct {
	// The position and size of the ellipse.
	//
	// These values are identical to the parent object's fields of the same
	// name, they are only provided for convenience.
	X, Y, Width, Height int
}

Ellipse represents an ellipse object, found in the Object.Value field.

type Image

type Image struct {
	// Format of the embedded image data (if any).
	Format string

	// The file path at which the image may be found
	Source string

	// The color in the image representing transparency (if any).
	//
	// The alpha (A) component of the color will always be 255.
	Trans color.RGBA

	// The width and height of the image (useful mostly only for correction
	// when the image's size changes from that known to the TMX file).
	Width, Height int
}

Image represents the source and properties of a image

func (*Image) String

func (i *Image) String() string

String returns a string representation of this image.

type Layer

type Layer struct {
	// The name of the layer.
	Name string

	// Value between 0 and 1 representing the opacity of the layer.
	Opacity float64

	// Boolean value representing whether or not the layer is visible.
	Visible bool

	// A map of 2D coordinates in this layer to so called "global tile IDs"
	// (gids).
	//
	// 2D coordinates whose gid's are zero (I.e. 'no tile') are not stored in
	// the map for efficiency reasons (as a good majority are zero).
	//
	// gids are global, since they may refere to a tile from any of the
	// tilesets used by the map. In order to find out from which tileset the
	// tile is you need to find the tileset with the highest Firstgid that is
	// still lower or equal than the gid. The tilesets are always stored with
	// increasing firstgids.
	Tiles map[Coord]uint32
}

Layer represents a single map layer and all of it's tiles

func (*Layer) String

func (l *Layer) String() string

String returns a string representation of this layer.

type Map

type Map struct {
	// Version of the map.
	//
	// E.g. VersionMajor=1, VersionMinor=0 for "1.0"
	VersionMajor, VersionMinor int

	// Orientation of the map.
	//
	// Like "orthogonal", "isometric" or "staggered".
	Orientation Orientation

	// Width and height of the map in tiles.
	Width, Height int

	// Width and height of a tile in pixels.
	TileWidth, TileHeight int

	// Background color of the map.
	//
	// Like "#FF0000".
	BackgroundColor color.RGBA

	// Map of property names and values for all properties set on the map.
	Properties map[string]string

	// A list of all loaded tilesets of this map.
	Tilesets []*Tileset

	// A list of all the layers of this map.
	Layers []*Layer

	// A list of all the object groups in this map.
	ObjectGroups []*ObjectGroup
}

Map represents a single TMX map file.

Although TileWidth and TileHeight describe the general size of tiles in pixels, individual tiles may have different sizes. Larger tiles will extend at the top and right (E.g. they are anchored to the bottom left).

func LoadFile

func LoadFile(path string, c *Config) (*Map, map[string]map[string]*gfx.Object, error)

LoadFile works just like Load except it loads all associated dependencies (external tsx tileset files, tileset texture images) for you.

Advanced clients who wish to have more control over file IO will use Load() directly instead of using this function.

func Parse

func Parse(data []byte) (*Map, error)

Parse parses the TMX map file data and returns a *Map.

nil and a error will be returned if there are any problems parsing the data.

func (*Map) FindTileset

func (m *Map) FindTileset(gid uint32) *Tileset

FindTileset returns the proper tileset for the given global tile id.

If the global tile id is invalid this function will return nil.

func (*Map) String

func (m *Map) String() string

String returns a string representation of this map.

func (*Map) TilesetRect

func (m *Map) TilesetRect(ts *Tileset, width, height int, spacingAndMargins bool, gid uint32) image.Rectangle

TilesetRect returns a image rectangle describing what part of the tileset image represents the tile for the given gid.

The image width and height must be passed as parameters because ts.Image.Width and ts.Image.Height are not always available.

If spacingAndMargins is true, then spacing and margins are applied to the rectangle.

func (*Map) TilesetTile

func (m *Map) TilesetTile(ts *Tileset, gid uint32) *Tile

TilesetTile returns the proper tile definition for the given global tile id.

If there is no tile definition for the given gid (can be common), or if the global tile id is invalid this function will return nil.

type Object

type Object struct {
	// The name of this object.
	Name string

	// The type of this object, which is an arbitrary string.
	Type string

	// The X and Y coordinates, as well as the width and height of this object
	// in pixels.
	X, Y, Width, Height int

	// The rotation of this object in degrees clockwise.
	Rotation float64

	// Reference to a tile (optional). If it is non-zero then this object is
	// represented by the image of the tile with this global ID. Currently that
	// means width and height are ignored for such objects. The image alignment
	// currently depends on the map orientation:
	//  Orthogonal - Aligned to the bottom-left
	//  Isometric - Aligned to the bottom-center
	Gid uint32

	// Boolean value representing whether or not the object group is visible.
	Visible bool

	// Map of properties for this object group.
	Properties map[string]string

	// Value represents the underlying object value (which is sometimes nil).
	// You can use a type switch to determine it's value:
	//  switch v := obj.Value.(type) {
	//  case *tmx.Ellipse: handleEllipse(obj, v)
	//  case *tmx.Polygon: handlePolygon(obj, v)
	//  case *tmx.Polyline: handlePolyline(obj, v)
	//  case *tmx.Image: handleImage(obj, v)
	//  }
	Value interface{}
}

Object represents a single object, which are generally used to add custom information to tile maps, like collision information, spawn points, etc.

func (*Object) String

func (o *Object) String() string

String returns a string representation of this object, like:

Object(Name="the name", X=%d, Y=%d, Width=%d, Height=%d)

type ObjectGroup

type ObjectGroup struct {
	// The name of this object group.
	Name string

	// Color of this object group.
	Color color.RGBA

	// Value between 0 and 1 representing the opacity of the object group.
	Opacity float64

	// Boolean value representing whether or not the object group is visible.
	Visible bool

	// Map of properties for this object group.
	Properties map[string]string

	// List of objects in this object group.
	Objects []*Object
}

ObjectGroup represents a group of objects.

func (*ObjectGroup) String

func (o *ObjectGroup) String() string

String returns a string representation of this object group, like:

ObjectGroup(Name="the name", 500 objects)

type Orientation

type Orientation int

Orientation represents the map's orientation. It will always be one of the predefined Orientation constants and will never be Invalid.

const (
	// Invalid orientation for catching zero-value related issues
	Invalid Orientation = iota

	// Orthogonal map orientation
	Orthogonal

	// Isometric map orientation
	Isometric

	// Staggered map orientation
	Staggered
)

type Point

type Point struct {
	X, Y int
}

Point represents a single point.

type Polygon

type Polygon struct {
	// The position/origin of the polygon.
	//
	// These values are identical to the parent object's fields of the same
	// name, they are only provided for convenience.
	X, Y int

	// Points making up the polygon, in pixels.
	Points []Point
}

Polygon represents a polygon object, found in the Object.Value field.

type Polyline

type Polyline struct {
	// The position/origin of the polyline.
	//
	// These values are identical to the parent object's fields of the same
	// name, they are only provided for convenience.
	X, Y int

	// Points making up the polyline, in pixels.
	Points []Point
}

Polyline represents a polyline object, found in the Object.Value field.

type TerrainType

type TerrainType struct {
	// Name of the terrain type
	Name string

	// Tile ID
	Tile int
}

TerrainType defines a single terrain with a name and associated tile ID

type Tile

type Tile struct {
	// The ID of the tile
	ID int

	// An array defining the terrain type of each corner of the tile, as indices
	// into the terrain types slice of the tileset this tile came from, in the
	// order of: top left, top right, bottom left, bottom right.
	//
	// -1 values have a meaning of 'no terrain'.
	Terrain [4]int

	// Percentage chance indicating the probability that this tile is chosen
	// when editing with the terrain tool.
	Probability float64

	// Map of properties for the tile
	Properties map[string]string

	// Image for the tile
	Image *Image
}

Tile represents a single tile definition and it's properties

func (*Tile) String

func (t *Tile) String() string

String returns a string representation of this tileset.

type Tileset

type Tileset struct {
	// The name of this tileset.
	Name string

	// The first global tile ID of this tileset (this global ID maps to the
	// first tile in this tileset).
	Firstgid uint32

	// The tilset source (tsx) file, if this tileset was loaded externally from
	// the TMX map.
	Source string

	// The maximum width/height of tiles in this tileset in pixels.
	Width, Height int

	// The horizontal and vertical offset of tiles in this tileset in pixels,
	// where +Y is down.
	OffsetX, OffsetY int

	// The spacing in pixels between the tiles in this tileset.
	Spacing int

	// The margin in pixels around the tiles in this tileset.
	Margin int

	// Map of property names and values for all properties set on the map.
	Properties map[string]string

	// The image of the tileset
	Image *Image

	// Tiles represents a map of tile ID's and their associated definitions.
	Tiles map[int]*Tile

	// The slice of terrain types
	Terrain []TerrainType
}

Tileset represents a tileset of a map, as loaded from the TMX file or from a external TSX file.

func (*Tileset) Load

func (t *Tileset) Load(data []byte) error

Load loads the specified data as this tileset or returns a error if the data is invalid.

If len(m.Source) == nil (I.e. if this tileset is not an external tsx file) then a panic will occur.

Clients should ensure properly synchronized read/write access to the tileset structure as this function write's to it's memory and does not attempt any synchronization with other goroutines who are reading from it (data race).

func (*Tileset) String

func (t *Tileset) String() string

String returns a string representation of this tileset.

Jump to

Keyboard shortcuts

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