ldtkgo

package module
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2021 License: MIT Imports: 8 Imported by: 9

README

LDtk-Go

LDtk-Go is a loader for LDtk v0.8.1 projects written in pure Go.

Screenshot

Generally, you first load a project using ldtkgo.LoadFile() or ldtkgo.LoadBytes(); afterward, you render the layers out to images, and then draw them onscreen with a rendering or game development framework, like ebiten, Pixel, raylib-go, or raylib-go-plus.

All of the major elements of LDtk should be supported, including Levels, Layers, Tiles, AutoLayers, IntGrids, Entities, and Properties.

Pkg.go.dev docs

Loading Projects

Using LDtk-Go is simple.

First, you load the LDTK project, either with ldtkgo.LoadFile() or ldtkgo.LoadBytes(). After that, you have access to the entire project in code. Currently, I believe all of LDtk projects and the major elements of each are fully accessible through this loader. Here's an excerpt from the provided example, showing loading an LDtk Project and then


ldtkProject *ldtkgo.Project
ebitenRenderer *renderer.EbitenRenderer

func main() {

	// Load the LDtk Project
    ldtkProject, err := ldtkgo.LoadFile("example.ldtk")

    if err != nil {
        panic(err)
    }
    
	// Choose a level...
	level := ldtkProject.Levels[0]

	// Create a new renderer...
	ebitenRenderer = renderer.NewEbitenRenderer()

	// ... And render the tiles for the level out to layers, which will be *ebiten.Images. We'll retrieve them to draw in a Draw() loop later.
	ebitenRenderer.Render(level)

}

As shown above, rendering is done by creating a renderer and using it to render with your framework of choice. An example is already provided for the ebiten and raylib frameworks, which can be used as a general guide for creating other renderers.

Running the Example

cd to the example directory, and then call go run ./ to run the example (as it's self-contained within its directory). The console will give instructions for interacting with the example.

Anything Else?

The core LDtk loader requires the encoding/json and image packages, as well as tidwall's gjson package. The ebiten renderer requires ebiten package as well, of course.

Documentation

Overview

Package ldtkgo is a loader for LDtk projects, written in Golang. The general idea is to load a project using ldtkgo.LoadFile() or ldtkgo.LoadBytes(), and then use the resulting Project. Generally, the smoothest way to use this in game development seems to be to render the layers out to images, and then draw them onscreen with a rendering or game development framework, like Pixel, raylib-go, or ebiten. All of the major elements of LDtk should be supported, including Levels, Layers, Tiles, AutoLayers, IntGrids, Entities, and Properties.

Index

Constants

View Source 
const (
	LayerTypeIntGrid  = "IntGrid"
	LayerTypeAutoTile = "AutoLayer"
	LayerTypeTile     = "Tiles"
	LayerTypeEntity   = "Entities"
)

LayerType constants indicating a Layer's type.

View Source 
const (
	WorldLayoutHorizontal = "LinearHorizontal"
	WorldLayoutVertical   = "LinearVertical"
	WorldLayoutFree       = "Free"
	WorldLayoutGridVania  = "GridVania"
)

WorldLayout constants indicating direction or layout system for Worlds.

Variables

This section is empty.

Functions

This section is empty.

Types

type BGImage 

type BGImage struct {
	Path     string
	ScaleX   float64
	ScaleY   float64
	CropRect []float64
}

BGImage represents a Level's background image as definied withing LDtk (the filepath, the scale, etc).

type Entity 

type Entity struct {
	Identifier string      `json:"__identifier"`   // Name of the Entity
	Position   []int       `json:"px"`             // Position of the Entity (x, y)
	Width      int         `json:"width"`          // Width  of the Entity in pixels
	Height     int         `json:"height"`         // Height of the Entity in pixels
	Properties []*Property `json:"fieldInstances"` // The Properties defined on the Entity
	Pivot      []float32   `json:"__pivot"`        // Pivot position of the Entity (a centered Pivot would be 0.5, 0.5)
}

An Entity represents an Entity as placed in the LDtk level.

func (*Entity) PropertyByIdentifier added in v0.8.2 

func (entity *Entity) PropertyByIdentifier(id string) *Property

PropertyByIdentifier returns a Property by its Identifier string (name).

type EnumSet added in v0.9.3 

type EnumSet []string

EnumSet represents a set of Enums applied to tiles; this is just for convenience so you can see if a Tile contains an enum easily.

func (EnumSet) Contains added in v0.9.3 

func (e EnumSet) Contains(enum string) bool

type Integer 

type Integer struct {
	Position []int `json:"-"`       // Not actually available from the LDtk file, but added in afterwards as a convenience
	Value    int   `json:"v"`       // The value of the Integer.
	ID       int   `json:"coordID"` // The ID of the Integer on the IntGrid.
}

Integer indicates the value for an individual "Integer Object" on the IntGrid layer.

type Layer 

type Layer struct {
	// The width and height of the layer
	Identifier string   `json:"__identifier"`     // Identifier (name) of the Layer
	GridSize   int      `json:"__gridsize"`       // Grid size of the Layer
	OffsetX    int      `json:"__pxTotalOffsetX"` // The offset of the layer
	OffsetY    int      `json:"__pxTotalOffsetY"`
	CellWidth  int      `json:"__cWid"` // Overall width of the layer in cell count (i.e. a 160x80 level with 16x16 tiles would have a CellWidth and CellHeight of 10x5)
	CellHeight int      `json:"__cHei"` // Overall height of the layer in cell count
	Type       string   `json:"__type"` // Type of Layer. Can be compared using LayerType constants
	Tileset    *Tileset `json:"-"`      // Reference to the Tileset used for this Layer (assuming the path is the same)
	// TilesetPath string     `json:"__tilesetRelPath"` // Relative path to the tileset image; already is normalized using filepath.FromSlash().
	TilesetUID int        `json:"__tilesetDefUid"` // The UID of the used tileset
	IntGrid    []*Integer `json:"-"`
	AutoTiles  []*Tile    `json:"autoLayerTiles"` // Automatically set if IntGrid has values
	Tiles      []*Tile    `json:"gridTiles"`
	Entities   []*Entity  `json:"entityInstances"`
	Visible    bool       `json:"visible"` // Whether the layer is visible in LDtk
}

Layer represents a Layer, which can be of multiple types (Entity, AutoTile, Tile, or IntGrid).

func (*Layer) AllTiles added in v0.8.2 

func (layer *Layer) AllTiles() []*Tile

AllTiles simply returns all of the tiles in the layer, regardless of whether they're AutoTiles or manually placed Tiles. This is a convenience function to keep you from rendering AutoTiles and Tiles in two different loops.

func (*Layer) AutoTileAt 

func (layer *Layer) AutoTileAt(x, y int) *Tile

AutoTileAt returns the AutoLayer Tile at the specified grid (not world) X and Y position. Note that this doesn't take into account the Layer's local Offset values (so a tile at 3, 4 on a layer with an offset of 64, 64 would still be found at 3, 4).

func (*Layer) EntityByIdentifier 

func (layer *Layer) EntityByIdentifier(identifier string) *Entity

EntityByIdentifier returns the Entity with the identifier (name) specified. If no Entity with the name is found, the function returns nil.

func (*Layer) FromGridPosition 

func (layer *Layer) FromGridPosition(x, y int) (int, int)

FromGridPosition converts the specified position from a position on the Layer's grid to world space. For example, if the layer were 128x128 and had 16x16 tiles, FromGridPosition(3, 4) would return (48, 64).

func (*Layer) IntegerAt 

func (layer *Layer) IntegerAt(x, y int) *Integer

IntegerAt returns the IntGrid Integer at the specified world X and Y position (rounded down to the Layer's grid). Note that this doesn't take into account the Layer's local Offset values (so a tile at 3, 4 on a layer with an offset of 64, 64 would still be found at 3, 4).

func (*Layer) TileAt 

func (layer *Layer) TileAt(x, y int) *Tile

TileAt returns the Tile at the specified grid (not world) X and Y position. Note that this doesn't take into account the Layer's local Offset values (so a tile at 3, 4 on a layer with an offset of 64, 64 would still be found at 3, 4).

func (*Layer) ToGridPosition 

func (layer *Layer) ToGridPosition(x, y int) (int, int)

ToGridPosition converts the specified position from a position in world space to a position on the Layer's grid. For example, if the layer were 128x128 and had 16x16 tiles, ToGridPosition(32, 16) would return (2, 1).

type Level 

type Level struct {
	BGImage       *BGImage `json:"-"` // Any background image that might be applied to this Level.
	WorldX        int      // Position of the Level in the LDtk Project / world
	WorldY        int
	Width         int         `json:"pxWid"` // Width and height of the level in pixels.
	Height        int         `json:"pxHei"`
	Identifier    string      // Name of the Level (i.e. "Level0")
	BGColorString string      `json:"__bgColor"`
	BGColor       color.Color `json:"-"`              // Background Color for the Level; will automatically default to the Project's if it is left at default in the LDtk project.
	Layers        []*Layer    `json:"layerInstances"` // The layers in the level in the project. Note that layers here (first is "furthest" / at the bottom, last is on top) is reversed compared to LDtk (first is at the top, bottom is on the bottom).
	Properties    []*Property `json:"fieldInstances"` // The Properties defined on the Entity
}

Level represents a Level in an LDtk Project.

func (*Level) LayerByIdentifier 

func (level *Level) LayerByIdentifier(identifier string) *Layer

LayerByIdentifier returns a Layer by its identifier (name). Returns nil if the specified Layer isn't found.

func (*Level) PropertyByIdentifier added in v0.8.2 

func (level *Level) PropertyByIdentifier(id string) *Property

PropertyByIdentifier returns a Property by its Identifier string (name).

type Project 

type Project struct {
	WorldLayout     string
	WorldGridWidth  int
	WorldGridHeight int
	BGColorString   string      `json:"defaultLevelBgColor"`
	BGColor         color.Color `json:"-"`
	JSONVersion     string
	Levels          []*Level
	Tilesets        []*Tileset
	IntGridNames    []string
}

Project represents a full LDtk Project, allowing you access to the Levels within as well as some project-level properties.

func Open added in v0.9.3 

func Open(filepath string) (*Project, error)

Open loads the LDtk project from the filepath specified. Returns the Project and an error should the loading process fail (unable to find the file, unable to deserialize the JSON).

func Read added in v0.9.3 

func Read(data []byte) (*Project, error)

Read reads the LDtk project using the specified slice of bytes. Returns the Project and an error should there be an error in the loading process (unable to properly deserialize the JSON).

func (*Project) IntGridConstantByName 

func (project *Project) IntGridConstantByName(constantName string) int

IntGridConstantByName returns the IntGrid constant index by a named string. If the string is not found, -1 is returned.

func (*Project) LevelAt 

func (project *Project) LevelAt(x, y int) *Level

LevelAt returns the level that "contains" the point indicated by the X and Y values given, or nil if one isn't found.

func (*Project) LevelByIdentifier 

func (project *Project) LevelByIdentifier(identifier string) *Level

LevelByIdentifier returns the level that has the identifier specified, or nil if one isn't found.

func (*Project) TilesetByIdentifier added in v0.9.3 

func (project *Project) TilesetByIdentifier(identifier string) *Tileset

type Property 

type Property struct {
	Identifier string      `json:"__identifier"`
	Type       string      `json:"__type"`  // The Type of the Property.
	Value      interface{} `json:"__value"` // The value contained within the property.
}

Property represents custom Properties created and customized on Entities.

func (*Property) AsArray 

func (p *Property) AsArray() []interface{}

AsArray returns a property's value as an array of interface{} values. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsBool 

func (p *Property) AsBool() bool

AsBool returns a property's value as a boolean value. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsColor 

func (p *Property) AsColor() color.Color

AsColor returns a property's value as a color.Color struct. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsFloat64 

func (p *Property) AsFloat64() float64

AsFloat64 returns a property's value as a float64. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsInt 

func (p *Property) AsInt() int

AsInt returns a property's value as an int. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsMap added in v0.9.3 

func (p *Property) AsMap() map[string]interface{}

AsMap returns a property's value as a map of string to interface{} values. As an aside, the JSON deserialization process turns LDtk Points into Maps, where the key is "cx" or "cy", and the value is the x and y position. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) AsString 

func (p *Property) AsString() string

AsString returns a property's value as a string. Can be used for strings, colors, enums, etc. Note that this function doesn't check to ensure the value is the specified type before returning it.

func (*Property) IsNull added in v0.9.3 

func (p *Property) IsNull() bool

type Tile 

type Tile struct {
	Position []int `json:"px"` // Position of the Tile in pixels (x, y)
	Src      []int // The source position on the texture to draw this texture
	Flip     byte  `json:"f"` // Flip bits - first bit is for X-flip, second is for Y. 0 = no flip, 1 = horizontal flip, 2 = vertical flip, 3 = both flipped
	ID       int   `json:"t"` // The ID of the Tile (starting from 0).
}

Tile represents a graphical tile (whether automatic or manually placed).

func (*Tile) FlipX added in v0.8.2 

func (t *Tile) FlipX() bool

FlipX returns if the Tile is flipped horizontally.

func (*Tile) FlipY added in v0.8.2 

func (t *Tile) FlipY() bool

FlipY returns if the Tile is flipped vertically.

type Tileset added in v0.9.3 

type Tileset struct {
	Path       string `json:"relPath"` // Relative path to the tileset image; already is normalized using filepath.FromSlash().
	ID         int    `json:"uid"`
	GridSize   int    `json:"tileGridSize"`
	Spacing    int
	Padding    int
	Width      int `json:"pxWid"`
	Height     int `json:"pxHei"`
	Identifier string
	CustomData map[int]string  `json:"-"` // Key: tileID, Value: custom data string
	Enums      map[int]EnumSet `json:"-"` // Key: enumValueID, Value: tileIDs (tile indices)
}

func (*Tileset) CustomDataForTile added in v0.9.3 

func (t *Tileset) CustomDataForTile(tileID int) string

CustomDataForTile returns the custom data defined for the tile of the ID given in the tileset. If no custom data is defined, a blank string is returned.

func (*Tileset) EnumsForTile added in v0.9.3 

func (t *Tileset) EnumsForTile(tileID int) EnumSet

EnumsForTile returns the EnumSet defined for the tile of the ID given in the tileset. If no enums are defined, an empty EnumSet is returned.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.