diff --git a/.gitignore b/.gitignore index 3ff4c8ba8..eeb36c458 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ site/ *.tmp* -*.pyc \ No newline at end of file +*.pyc +.DS_Store +venv/ \ No newline at end of file diff --git a/docs/manual/editor/add-atlas-source.png b/docs/manual/editor/add-atlas-source.png new file mode 100644 index 000000000..69e97e87a Binary files /dev/null and b/docs/manual/editor/add-atlas-source.png differ diff --git a/docs/manual/editor/map-brush-paint.png b/docs/manual/editor/map-brush-paint.png new file mode 100644 index 000000000..bc21d42da Binary files /dev/null and b/docs/manual/editor/map-brush-paint.png differ diff --git a/docs/manual/editor/overview.md b/docs/manual/editor/overview.md new file mode 100644 index 000000000..5897ed0b0 --- /dev/null +++ b/docs/manual/editor/overview.md @@ -0,0 +1,28 @@ +# Luxe Editor + +## Omni + +Omni Docs TODO + +## Contexts + +A Context is a mode of the editor. + +### Project Context + +In the Project context, you can inspect project info, and make builds for distribution. + +### World Context + +World context TODO + +### Tiles Context + +The Tiles Context lets you define tileset and draw tile maps, which can be loaded into the scene +in a _Tile_ Entity. + +Read more about the [Tiles Editor](../tiles). + +### Assets Context + +Assets Context TODO \ No newline at end of file diff --git a/docs/manual/editor/stack-preview.png b/docs/manual/editor/stack-preview.png new file mode 100644 index 000000000..8f1b724ac Binary files /dev/null and b/docs/manual/editor/stack-preview.png differ diff --git a/docs/manual/editor/tile-brush-paint.png b/docs/manual/editor/tile-brush-paint.png new file mode 100644 index 000000000..706979004 Binary files /dev/null and b/docs/manual/editor/tile-brush-paint.png differ diff --git a/docs/manual/editor/tile-brush-select.png b/docs/manual/editor/tile-brush-select.png new file mode 100644 index 000000000..e837ade27 Binary files /dev/null and b/docs/manual/editor/tile-brush-select.png differ diff --git a/docs/manual/editor/tile-settings.png b/docs/manual/editor/tile-settings.png new file mode 100644 index 000000000..ef3eb39d0 Binary files /dev/null and b/docs/manual/editor/tile-settings.png differ diff --git a/docs/manual/editor/tiles-adjusted.png b/docs/manual/editor/tiles-adjusted.png new file mode 100644 index 000000000..72c1a3ba5 Binary files /dev/null and b/docs/manual/editor/tiles-adjusted.png differ diff --git a/docs/manual/editor/tiles-collide.png b/docs/manual/editor/tiles-collide.png new file mode 100644 index 000000000..d72327510 Binary files /dev/null and b/docs/manual/editor/tiles-collide.png differ diff --git a/docs/manual/editor/tiles-rotate-offset.png b/docs/manual/editor/tiles-rotate-offset.png new file mode 100644 index 000000000..99d30a912 Binary files /dev/null and b/docs/manual/editor/tiles-rotate-offset.png differ diff --git a/docs/manual/editor/tiles-tags.png b/docs/manual/editor/tiles-tags.png new file mode 100644 index 000000000..4d67f1216 Binary files /dev/null and b/docs/manual/editor/tiles-tags.png differ diff --git a/docs/manual/editor/tiles-visual-source.png b/docs/manual/editor/tiles-visual-source.png new file mode 100644 index 000000000..dd5eb824e Binary files /dev/null and b/docs/manual/editor/tiles-visual-source.png differ diff --git a/docs/manual/editor/tiles.md b/docs/manual/editor/tiles.md new file mode 100644 index 000000000..f1d0c1ae2 --- /dev/null +++ b/docs/manual/editor/tiles.md @@ -0,0 +1,177 @@ +# Tiles Editor + +## The Grid + +Tiles live in a grid. In many classic games, the tile grid was stored as an array of tile indexes, and the engine would +render the tiles, allowing a large world without using very much memory. + +In Luxe, the grid is not required for rendering efficiency, but as a design constraint and tool. Many tricks and techniques +have been developed that take advantage of tilemap workflows, and they can be a powerful artistic and creative tool. Luxe +tilemaps let you use the tile grid as a design constraint without having to be limited to fixed size or placement. + +There is no overall boundary for the tilemap grid. In fact a tile can be placed at negative coordinates. A tilemap is just +a collection of tiles. Each cell in a tilemap can have a stack of multiple tiles at different _depths_, in that way +the map can be built of multiple layer of overlapping tiles. + +![](tiles-adjusted.png){width="75%"} + +Here's some examples of tiles on the grid: Tiles may be placed at negative coordinates, they may be flipped, +offset and scaled, and multiple tiles may be stacked in one tile space. + +### Settings + +The Settings panel in Omni defines the overall grid that the tiles use. + +![](tile-settings.png){width="75%"} + +You can change the grid size and press 'Apply' to apply the new size to the tile map. If the +grid size is smaller than the tile size, tiles will overlap and if the grid size is larger, +gaps will appear. + +- **Background Color** This sets the background color in the editor display. + +### Inspector + +When you hover the cursor over the tile map, it displays an inspector that lists all the tiles stacked +at the current location. + +![](stack-preview.png){width="75%"} + +In this example there is a ground tile, a snow border tile, and a tree stump tile at this location. You can also +inspect the attributes such as flip and offset, and the `tags` for each tile in the stack. + +#### Working with Depth + +The cursor has a current depth. You can press `W` and `S`, or `Up Arrow` and `Down Arrow` to adjust the current depth, +or hold `SHIFT` and use the scroll wheel. + +For tools that work with depth, such as _Select_ and _Erase_, you can hold `ALT` to apply the tool to all tiles in the +stack regardless of depth. + +### Visual Sources + +Each tile has a _Visual_ that comes from a _Visual Source_. Usually this is a tile +sheet image, with the tiles layed out in a regular grid, but it could be a single image +for one tile as well. The tilemap can mix visuals from several visual source images in one map. + +![](tiles-visual-source.png){width="75%"} + +The visual source panel shows a preview of the visual sources, with sliders to control +the size and the background brightness for transparent images. + +#### Adding a Visual Source + +In the **Visual Source** panel in Omni, press "Add Visual Source". You can choose what type of source to add: + +#### **sheet/atlas source** + +This adds tiles from an image with tiles arranged in a grid, often called a 'tile sheet', or 'atlas'. + +![](add-atlas-source.png){width="50%"} + +- **source id** - A unique name for the source. Tiles use this to identify which source they come from. +- **material** - The material with which the tiles will be rendered. +- **material input** - Normally not changed. If your material uses a different image name, set it here. +- **number of tiles in x (columns)** +- **number of tiles in y (rows)** +- **pixelated visuals** - Whether the tilemap should be displayed with sharp pixels in preview and tile palette. + +#### **image source** + +Adding an image source will make a visual source with a single image. The visual size will be detected automatically +from the image. + + +### Brushes + +Painting on the tilemap is done with **Brushes**. A brush is a group of tiles arranged together. For example, if you +had a 2x2 tuft of grass, you could have a brush with 4 tiles. + +In the simplist case, a brush is just a single tile. +Choose the Brush tool from the tools, then click in the tile visuals to select a single tile brush this way. + +#### Painting Offset, flip and rotation + +When painting, you can press `F` and `V` to flip the brush horizontally or vertically. + +You can hold `R` and drag the mouse up and down to rotate the tile. Holding `Shift` will snap the rotation to even +multiples. + +Painting offset tiles can be a little confusing but it is a powerful tool. If you hold down `alt` or `option` on mac, +the brush will no longer be snapped to the grid, and you can paint anywhere. However, keep in mind that this doesn't +actually paint freehand, it is assigning the tile to the nearest grid square as usual, but then setting the offset +to the brush position. So if you offset several tiles nearby at the same depth, it may sometimes look like it is erasing +tiles that are already placed, but it is really just replacing the tile with a different offset. + +!!! note "" + Painting offset tiles at different depths lets you cover a lot of area. + +![](tiles-rotate-offset.png){width="50%"} + + +Rotating and offset tiles are extremely useful, especially to add variation to decals and avoid the repeated look. + +### Multi-tile brushes + +To define a more complicated brush, hold down `Shift` and select multiple tiles from the visual list. It is +helpful to use the size slider to make the rows/cols match your source. + +![](tile-brush-select.png){width="50%"} + +Now, when you paint with the brush tool, the set of tiles will be stamped as a single unit. + +![](tile-brush-paint.png){width="50%"} + +#### Stamping Tiles + +You can use the editor window like a scratchpad to define a compound brush. + +To do this, hold down `CTRL` when drawing tiles on the main editor screen. You can +draw the tile in any pattern or configuration. The tiles will appear on top of +the existing map, and be drawn with a blue highlight. + +![](map-brush-paint.png){width="50%"} + +Then, when you release `CTRL`, the tiles will not be stamped on the map but instead +be used at the current brush. + + + + +!!! warning + I'm not sure how to properly handle the videos here. I just dropped a link to the copy from + discord's CDN but you might want to move these. :) + + +You can even repeat this and hold `CTRL` and stamp the brush to make a larger brush, to +build up larger and more complicated shapes! And using the Flip (`F` and `V`) commands work on the +entire brush. + +#### From the Map + +You can also grab a brush from the map. In `Select` mode, select some tiles. You can hold `CTRL` to select +a rectangular region, or `SHIFT`-select multiple tiles. Then press Copy (`CTRL-V` or `Cmd-V`) to make a brush +from them. This will automatically switch to the the Brush tool. + +You can even combine these approaches to quickly build up levels. + + + +### Setting Tags + +You can add tags to tiles which can be read by other gameplay modules. + +![](tiles-tags.png){width="50%"} + +In this example, the runtime looks for the `solid` tag to provide collision information that we can see in the debug overlay: + +![](tiles-collide.png){width="50%"} + +### Erasing tiles + +The `E` Key activates the Erase tool. This erases tiles at the current depth. + diff --git a/docs/manual/overview.md b/docs/manual/overview.md index 42221e500..60270118f 100644 --- a/docs/manual/overview.md +++ b/docs/manual/overview.md @@ -10,6 +10,8 @@ The manual is split into sections, some quick and some in depth. - Modifiers, UI, 2D drawing and some old tutorials. - **[How to...](../how-to) is a short and easy answer to many questions.** - How to generate random numbers, use separate files with wren, and more. +- **The [editor](../editor/overview) manual covers the interactive editor.** + - Working with World, Assets, Tiles and more in the editor. - **The [runtime](../runtime/overview) manual goes over the engine lifecycle.** - Covering details like the main loop, event systems and entry system. - **The [asset system](../assets/overview) manual goes over how assets work.** diff --git a/mkdocs.yml b/mkdocs.yml index b0d705750..c160fec8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,9 @@ nav: - moving a sprite : manual/wip/moving-a-sprite.md - create a scene : manual/wip/create-a-scene.md - how to ...: manual/how-to.md + - editor: + - overview: manual/editor/overview.md + - tiles: manual/editor/tiles.md - runtime: - overview: manual/runtime/overview.md - asset pipeline: @@ -122,5 +125,5 @@ plugins: - exclude: glob: - usage.md - # - api.md - # - api/** \ No newline at end of file + # - api.md + # - api/** \ No newline at end of file