[READ-ONLY] Mirror of https://github.com/excaliburjs/Excalibur. 🎮 Your friendly TypeScript 2D game engine for the web 🗡️
excaliburjs.com
excalibur
excaliburjs
game-development
game-engine
game-framework
gamedev
games
html5-canvas
typescript
docs: adds additional details to building up an isometric scene (#3411)
+99
-7
+1
-1
site/docs/01-getting-started/01-installation.mdx
+1
-1
site/docs/01-getting-started/01-installation.mdx
+98
-6
site/docs/08-tile-maps/07-isometricmap.mdx
+98
-6
site/docs/08-tile-maps/07-isometricmap.mdx
···
4
4
section: TileMaps
5
5
---
6
6
7
-
Excalibur can produce isometric style tile maps! Isometric tilemaps, also known as 2.5D, provide a way to draw maps from a simulated 45 degree camera view.
7
+
Excalibur can produce isometric style tile maps! Isometric tilemaps, also known as 2.5D, provide a way to draw maps from
8
+
a simulated 45 degree camera view.
9
+
10
+
Excalibur has a [Tiled plugin](https://github.com/excaliburjs/excalibur-tiled) to automatically create tilemaps from
11
+
isometric maps created in the popular [Tiled](https://www.mapeditor.org/) editor. We generally recommend using the
12
+
plugin, however, read on to understand how isometric tilemaps function in Excalibur.
8
13
9
14
10
15
···
14
19
15
20
## Isometric Map Usage
16
21
17
-
Use the excalibur type [[IsometricMap]] for drawing isometric grids! (They also support custom colliders via the same mechanism as `ex.TileMap`)
22
+
Use the Excalibur [[IsometricMap]] class for drawing isometric grids! (They also support custom colliders via the same mechanism as `ex.TileMap`)
18
23
19
24
```typescript
20
25
const game = new ex.Engine({...});
···
23
28
pos: ex.vec(250, 10),
24
29
tileWidth: 32,
25
30
tileHeight: 16,
26
-
columns: 15,
27
-
rows: 15
31
+
columns: 5,
32
+
rows: 5
28
33
});
29
34
30
35
game.currentScene.add(isoMap);
···
35
40
36
41
The [[IsometricEntitySystem]] generates a new z-index based on the `elevation` and [[y position|TransformComponent]] of an entity with [[IsometricEntityComponent]].
37
42
43
+
The 5x5 IsometricMap map from the above example snippet will contain 25 `IsometricTile`'s. These are accessible via the `tiles` property on the `IsometricMap` instance. e.g. `isoMap.tiles`. The IsometricMap represents a single layer in an isometric scene.
44
+
45
+
At this stage the `IsometricTile`'s do not have graphics attached, so they are invisible to the human eye. But the `IsometricMap` that has been added to the scene can be thought of as:
46
+
47
+
48
+
38
49
## Selecting an appropriate Tile Height
39
50
40
51
When defining the `tileHeight` there are a few considerations you should make relative to your asset. Usually the `tileHeight` is half your graphics total height. With other art assets the `tileHeight` can be different, in this case roughly half the height of the asset. This height will depend on your art assets.
···
70
81
71
82
## Adding Graphics to IsometricTiles
72
83
73
-
Graphics can be added to an [[IsometricTile]], graphics are drawn differently from other parts of excalibur. They are drawn from the bottom left, this is done to help preserve the illusion of placing tiles on top of a grid.
84
+
Graphics can be added to an [[IsometricTile]]. Graphics are drawn differently from other parts of Excalibur, they are drawn from the bottom left, this is done to help preserve the illusion of placing tiles on top of a grid.
74
85
75
-
86
+
76
87
77
88
```typescript
78
89
const isoMap = new ex.IsometricMap({...});
···
95
106
renderFromTopOfGraphic: true;
96
107
});
97
108
```
109
+
110
+
## Working with depth and elevation
111
+
112
+
As noted above, an `IsometricMap` represents a single layer in an isometric scene. To add some depth to a scene we can "stack" multiple `IsometricMap`'s, adjusting the `elevation` and `y` of each subsequent `IsometricMap`. This will give the desired effect of tiles appearing on top of another.
113
+
114
+
For more advanced maps, with multiple layers, we recommend using the [Tiled plugin](https://github.com/excaliburjs/excalibur-tiled) which handles the complexity automatically.
115
+
116
+
```typescript
117
+
export class MyLevel extends Scene {
118
+
private layers = [
119
+
[ // Floor
120
+
[0, 0, 1, 1, 0],
121
+
[3, 3, 3, 3, 3],
122
+
[3, 3, 3, 3, 3],
123
+
[3, 3, 3, 3, 3],
124
+
[3, 3, 3, 3, 3],
125
+
],
126
+
[ // Wall layer 1
127
+
[1, 0, 0, 0, 0],
128
+
[1, 1, 0, 0, 1],
129
+
[1, 2, 0, 0, 2],
130
+
[1, 0, 0, 0, 0],
131
+
[1, 0, 0, 0, 0],
132
+
],
133
+
[ // Wall layer 2
134
+
[0, 0, 0, 0, 0],
135
+
[1, 1, 0, 0, 1],
136
+
[1, 0, 0, 0, 0],
137
+
[1, 0, 0, 0, 0],
138
+
[1, 0, 0, 0, 0],
139
+
],
140
+
];
141
+
142
+
override onInitialize(): void {
143
+
const image = SpriteSheet.fromImageSource({
144
+
image: Resources.Tiles,
145
+
grid: {
146
+
rows: 3,
147
+
columns: 6,
148
+
spriteWidth: 32,
149
+
spriteHeight: 32,
150
+
},
151
+
});
152
+
153
+
this.layers.forEach((layer, index) => {
154
+
const isoMap = new IsometricMap({
155
+
pos: vec(300, 184 + index * -16),
156
+
tileWidth: 32,
157
+
tileHeight: 16,
158
+
columns: layer.length,
159
+
rows: layer[0].length,
160
+
elevation: index,
161
+
});
162
+
163
+
this.add(isoMap);
164
+
165
+
// This is a primitive approach of manually assigning a tile based
166
+
// on the input data. In reality, you will probably use more
167
+
// advanced techniques such as using information contained in a
168
+
// Tiled map file
169
+
//
170
+
isoMap.tiles.forEach((tile) => {
171
+
if (layer[tile.y][tile.x] === 1) {
172
+
tile.addGraphic(image.getSprite(0, 0));
173
+
}
174
+
if (layer[tile.y][tile.x] === 2) {
175
+
tile.addGraphic(image.getSprite(3, 0));
176
+
}
177
+
if (layer[tile.y][tile.x] === 3) {
178
+
tile.addGraphic(image.getSprite(5, 0));
179
+
}
180
+
});
181
+
});
182
+
}
183
+
}
184
+
185
+
186
+
```
187
+
188
+
189
+
98
190
99
191
## Adding Colliders to IsometricTiles
100
192
site/docs/08-tile-maps/isometric-map-elevation.png
site/docs/08-tile-maps/isometric-map-elevation.png
This is a binary file and will not be displayed.
site/docs/08-tile-maps/isometric-map-order.png
site/docs/08-tile-maps/isometric-map-order.png
This is a binary file and will not be displayed.
site/docs/08-tile-maps/isometric-map.png
site/docs/08-tile-maps/isometric-map.png
This is a binary file and will not be displayed.