You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+34-21Lines changed: 34 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,32 +2,33 @@
2
2
3
3
`TileMaps` is a package that makes it simple to create 2D tile maps in Julia. It is designed to be lightweight and fast, and have minimal dependencies.
4
4
5
-
**Note:** This package does not export any symbols. The examples below that demonstrate the use of this package assume that it has been loaded via `import TileMaps as TM`.
5
+
**Note:** This package does not export any names. The examples below that demonstrate the use of this package assume that it has been loaded via `import TileMaps as TM`.
6
6
7
7
**Acknowledgements:** Big thanks to [Jun Tian](https://github.com/findmyway) (@findmyway) for initially introducing the core ideas of this package in [`GridWorlds`](https://github.com/JuliaReinforcementLearning/GridWorlds.jl).
8
8
9
9
### Index
10
10
11
-
1.[TileMap](#tilemap)
11
+
1.[ObjectIndexableArray](#objectindexablearray)
12
12
1.[Objects](#objects)
13
+
1.[TileMap](#tilemap)
13
14
1.[Constructing a TileMap](#constructing-a-tilemap)
14
15
1.[Indexing a TileMap](#indexing-a-tilemap)
15
16
1.[Visualizing a TileMap](#visualizing-a-tilemap)
16
17
17
-
### TileMap
18
+
19
+
### `ObjectIndexableArray`
18
20
19
21
```
20
-
struct TileMap{O} <: AbstractArray{Bool, 3}
21
-
grid::BitArray{3}
22
-
objects::O
22
+
struct ObjectIndexableArray{T, N, A, O} <: AbstractArray{T, N}
23
+
array::A
23
24
end
24
25
```
25
26
26
-
We'll refer to an instance of `TileMap` as `tile_map`. A `tile_map` contains a field called `grid` of type `BitArray{3}`and size `(num_objects, height, width)`, which efficiently stores the objects present in the `tile_map`. Each tile can contain multiple objects, which is captured by a multi-hot encoding along the first dimension (`num_objects` dimension) of the `grid`.
27
+
We'll refer to an instance of `ObjectIndexableArray` as `object_indexable_array`. An `object_indexable_array` simply wraps an `array`and allows us to index its first dimension using a [singleton](https://docs.julialang.org/en/v1/manual/types/#man-singleton-types) object or an array of singleton objects (in addition to all the other ways of indexing `array`).
27
28
28
29
### Objects
29
30
30
-
Objects are [singletons](https://docs.julialang.org/en/v1/manual/types/#man-singleton-types) (structs with no fields). Here is how objects are created inside this package:
31
+
Object types are [singletons](https://docs.julialang.org/en/v1/manual/types/#man-singleton-types) (structs with no fields). Here are the example objects that are provided in this package:
31
32
32
33
```
33
34
abstract type AbstractObject end
@@ -50,27 +51,37 @@ julia> struct MyObject <: TM.AbstractObject end
We'll refer to an instance of `TileMap` as `tile_map`. A `tile_map` wraps an `array` of size `(num_objects, height, width)`, which encodes information about the presence or absence of objects across the tiles. Each tile can contain multiple objects, which is captured by a multi-hot encoding along the first dimension (`num_objects` dimension) of the `array`.
61
+
53
62
### Constructing a `TileMap`
54
63
55
-
You can instantiate a `TileMap` using a constructor that is provided by this package. The following creates an empty tile map using a tuple of objects along with the desired height and width:
64
+
You can instantiate a `TileMap` using the following constructor that are provided by this package:
In addition to the normal ways of indexing an array, you can also use an object or an array of objects to index the first dimension of a `tile_map`. For example, something like this:
84
+
Because of `TileMap <: ObjectIndexableArray`, we can index the first dimension of a `tile_map` in a variety of ways. For example, like this:
74
85
75
86
```
76
87
julia> tile_map[TM.EXAMPLE_OBJECT_3, 4, 6]
@@ -92,23 +103,25 @@ julia>
92
103
93
104
### Visualizing a `TileMap`
94
105
95
-
Using the [`Crayons`](https://github.com/KristofferC/Crayons.jl) package, each object can be displayed as a colored Unicode character:
106
+
Using the [`Crayons`](https://github.com/KristofferC/Crayons.jl) package, each object can be displayed as a colored Unicode character. For example, like this:
you may also want to implement the following methods: `get_char(::MyObject)` (especially this one), `get_foreground_color(::MyObject)`, and `get_backround_color(::MyObject)`. If you don't do so, it will be displayed based on the following default methods defined in this package:
114
+
you may also want to implement the following methods: `get_char(::MyObject)` (especially this one), `get_foreground_color(::MyObject)`, and `get_backround_color(::MyObject)`. If you don't do so, `MY_OBJECT` will be displayed based on the following default methods as defined in this package:
104
115
105
116
```
106
117
get_char(object::Any) = '?'
107
118
get_foreground_color(object::Any) = :white
108
119
get_backround_color(object::Any) = :nothing
109
120
```
110
121
111
-
A `tile_map` is displayed as a 2D grid of colored Unicode characters, with one character displayed per tile. Only the first object present at a tile (along the first dimension (`num_objects` dimension) of the `grid`) is displayed for that tile, even though there may be multiple objects present at that tile. If there are no objects present at a tile, then the `⋅` character is displayed for that tile (with white color). This behaviour can be customized by overriding the following methods:
122
+
A `tile_map` is displayed as a 2D grid of colored Unicode characters, with one character displayed per tile. Only the first object present (along the first dimension (`num_objects` dimension) of the `array`) at a tile is displayed for that tile, even though there may be multiple objects present at that tile.
123
+
124
+
If there are no objects present at a tile, then the `⋅` character is displayed for that tile (with white color and no background). This behaviour can be customized by overriding the following methods:
Note that the `get_char`, `get_foreground_color`, and `get_background_color` methods have purposefully not been defined for the `TM.ExampleObject3` type in order to demonstrate the fallback to the default character and colors, which is why `TM.EXAMPLE_OBJECT_3` is displayed using a white colored `?` with no background.
134
+
Note that the `get_char`, `get_foreground_color`, and `get_background_color` methods have purposefully not been explictly defined for the `TM.ExampleObject3` type in order to demonstrate the fallback to the default character and colors, which is why `TM.EXAMPLE_OBJECT_3` is displayed using a white colored `?` with no background.
122
135
123
136
We can also inspect each kind of object in the `tile_map` separately using the `show_layers` method. This is very handy for debugging:
Here we have used only a limited number of features (foreground and background colors) from the [`Crayons`](https://github.com/KristofferC/Crayons.jl) package for showing an example of how one may want to display a `tile_map`. It has several other features that you can play with to suit your needs.
140
+
Here we have utilized only a limited number of features from the `Crayons` package in order to show an an example of how one may want to display a `tile_map`. `Crayons` has other features that you can play with to suit your needs.
0 commit comments