Skip to content

Commit

Permalink
docs are becoming better
Browse files Browse the repository at this point in the history
  • Loading branch information
Cammin committed Sep 28, 2023
1 parent c555551 commit 220cee5
Show file tree
Hide file tree
Showing 9 changed files with 102 additions and 78 deletions.
58 changes: 0 additions & 58 deletions DocFX/documentation/Importer/topic_ProjectImporter.md
Original file line number Diff line number Diff line change
@@ -1,62 +1,5 @@
# Project Importer

This will be a step-by-step guide for how to use the Unity importer for LDtk.
Lower down in the page contains information regarding the project's importer inspector.

## Setup Guide

The importer is structured where it separates the handling of tileset definitions into separate **[Tileset Files](topic_TilesetImporter.md)**.
For that reason, this initial setup process is required so that tileset files are automatically generated after saving in LDtk.

This guide entails three major steps:
- Adding a LDtk project to the unity project
- Installing an exporter app into the Library folder
- Configuring the LDtk project to run a custom command on the exporter app

### 1. Add to the Project
Store the LDtk project file in the Unity project so that it can be imported.
- The file format must be `.ldtk`.
![Use Extension](../../images/img_ldtk_UseLDtkExtension.png)
- If the LDtk project was outside the unity project originally,
make sure that all images are also transferred, and maintain their relativity with the LDtk project.
LDtk files require a direct relative connection to the image files.
- You can test if the images were successfully moved by opening the LDtk project and seeing if the images were loaded successfully in LDtk.

### 2. Install the Export App
The export app will generate tileset files.
- Select the LDtk project in Unity to show the importer inspector.
- You will notice an error displayed at the top instructing to install the export app.
![Install Button](../../images/img_Unity_InstallTilesetExporter.png)
- Click the Install button.
- After clicking, a new app is added to the Unity project's Library folder.
- The code of the app available here:
**[LDtkTilesetExporter on GitHub](https://github.com/Cammin/LDtkTilesetExporter)**

### 3. Add a Custom Command
Now that the app is installed, LDtk can execute a command to run this app. But we still need to add the command to LDtk.
- Again, select the LDtk project in Unity to show the importer inspector.
- You will notice an error displayed at the top instructing to configure the project with a custom command.
![Fix Button](../../images/img_Unity_FixTilesetExporter.png)
- From here, there are two ways to add the command to the project: automatically, or manually.
- **Automatic:**
Click the "Fix" button.
A new dialogue will appear.
Ensure all LDtk apps are closed, and click the "Auto-add command" button.
A new dialogue will appear, asking to open the project and save.
Open & save your LDtk project, and you're ready!
- **Manual:**
Click the "Copy" button. This copies the command to the clipboard.
Open the LDtk project, and open the project settings. From there, find the "Custom Commands" area.
Once there, create a new command, paste the command in the field, and change the timing to "Run after saving".
Save your LDtk project, and you're ready!
![Fix Button](../../images/img_ldtk_customCommands.png)
- When saving with a custom command for the first time, LDtk will display a disclaimer. Select "I understand the risks, allow commands".
- If you're in doubt, the code of the app is available **[here](https://github.com/Cammin/LDtkTilesetExporter)**.

After you're ready drag the project from the project window into the scene or the hierarchy.
![Drag-N-Drop](../../images/gif_DragNDrop.gif)
Tip: Double clicking the LDtk file in the project window will conveniently open the project in LDtk.

## Inspector
The importer inspector is composed of several sections:
[**Main**](topic_Section_Main.md),
Expand All @@ -68,7 +11,6 @@ and [**Dependencies**](topic_Section_Dependencies.md).
- After making any changes, click the apply button at the bottom to reimport.
- If any section is hidden, it's because there were no associated definitions in the LDtk project.


## Hierarchy
The imported project generates a hierarchy of GameObjects.
All of the objects have accompanying scripts that contain useful data.
Expand Down
13 changes: 5 additions & 8 deletions DocFX/documentation/Importer/topic_Section_IntGrids.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
# IntGrids Section

Assign [**IntGrid Tiles**](../Topics/topic_IntGridTile.md) for collision.
Assign [**IntGrid Tiles**](../Topics/topic_IntGridTile.md) for collision.

Create a new Int Grid Tile with the button at the top-right region of the inspector.
![Section](../../images/img_Unity_Section_IntGrids.png)


- All of the IntGrid layers and their values are displayed here for assigning.
- The IntGrid Tiles are intended for collision first and foremost.
However there are also options for simple rendering, or GameObjects in tile-space.

- If a field is left empty, then a default tile would be used.
- This tile is a square with no collision.
- The IntGrid Tiles are primarily used for collision, however there are also options for simple rendering, or GameObjects in tile-space.

- Choose whether to render IntGrid Tiles in the [**Main Section**](topic_Section_Main.md).
- Choose whether to render IntGrid Tiles in the [**Main Section**](topic_Section_Main.md).
- The fields also accept TileBase, so any kind of custom tile is allowed. However if you use IntGrid tiles, there's options for separating Tag/Layer/PhysicsMaterial.
31 changes: 24 additions & 7 deletions DocFX/documentation/Importer/topic_TilesetImporter.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
# Tileset Importer

The importer creates tileset files, which generate the sprites and tiles.
- The file format for tileset files is `.ldtkt`.
- The files are required to use the importer, and are not generated initially.
- Only modified tileset files will reimport, resulting in less unnecessary imports when applicable. Generating sprites and tiles are a marginal portion of the heavy work.
- Tileset files can be added to a SpriteAtlas asset, and will pack all the sub-sprites generated.

## Sprite Editor
This importer interacts with the sprite editor window much like a Texture Importer. You can define physics shapes through this file!
- The file format for tileset files is `.ldtkt`.
- The files are required to use the importer, and are not generated initially.
- Only modified tileset files will reimport, resulting in less unnecessary imports when applicable. Generating sprites and tiles are a marginal portion of the heavy work.
- Tileset files can be added to a SpriteAtlas asset, and will pack all the sub-sprites generated.
- Tiles have their CustomData and EnumTags available inside them

## Inspector
The importer inspector displays a reference to the level's project which can be clicked to locate the project in the hierarchy window.
Expand All @@ -19,3 +17,22 @@ Tile assets pixels per unit. This should always match with the project's Pixels

### Depend On Dependencies
Used by all LDtk assets. [See here.](topic_Section_Dependencies.md#depend-on-dependencies)

## Sprite Editor
This importer interacts with the sprite editor window similar to a Texture Importer.
Select a Tileset file and open the sprite editor window.

You can define physics shapes which will reflect in
![Sprite Editor](../../images/img_Unity_SpriteEditor.png)
If you are unfamiliar with the sprite editor window, you can explore more of it's use [**here**](https://docs.unity3d.com/Manual/SpriteEditor.html).

Tile/Auto layers will include these tiles, and have the corresponding collision, if defined.

#### Note
- Unlike the TextureImporter, this sprite editor will always have a fixed amount of rectangles and their rectangle\names will revert back upon applying changes.
Everything else is adjustable. This includes:
- Secondary Textures
- Physics Shape
- Pivot
- Border
- The imported tilemaps with these collisions shapes currently have no options for assigning tag/layer/physics material, and so will require postprocessing to have finer control. However, options may come later.
3 changes: 3 additions & 0 deletions DocFX/documentation/Installation/toc.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
- name: Install
href: topic_Install.md

- name: Setup Guide
href: topic_SetupGuide.md

- name: Update
href: topic_Update.md

Expand Down
67 changes: 67 additions & 0 deletions DocFX/documentation/Installation/topic_SetupGuide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Setup Guide
This will be a step-by-step guide for how to use the Unity importer for LDtk.
Lower down in the page contains information regarding the project's importer inspector.


The importer is structured where it separates the handling of tileset definitions into separate **[Tileset Files](topic_TilesetImporter.md)**.
For that reason, this initial setup process is required so that tileset files are automatically generated after saving in LDtk.

This guide entails three major steps:
- Adding a LDtk project to the unity project
- Installing an exporter app into the Library folder
- Configuring the LDtk project to run a custom command on the exporter app

### 1. Add to the Project
Store the LDtk project file in the Unity project so that it can be imported.
- The file format must be `.ldtk`.
![Use Extension](../../images/img_ldtk_UseLDtkExtension.png)
- If the LDtk project was outside the unity project originally,
make sure that all images are also transferred, and maintain their relativity with the LDtk project.
LDtk files require a direct relative connection to the image files.
- You can test if the images were successfully moved by opening the LDtk project and seeing if the images were loaded successfully in LDtk.

### 2. Install the Export App
The export app will generate tileset files.
- Select the LDtk project in Unity to show the importer inspector.
- You will notice an error displayed at the top instructing to install the export app.
![Install Button](../../images/img_Unity_InstallTilesetExporter.png)
- Click the Install button.
- After clicking, a new app is added to the Unity project's Library folder.
- The code of the app available here:
**[LDtkTilesetExporter on GitHub](https://github.com/Cammin/LDtkTilesetExporter)**

### 3. Add a Custom Command
Now that the app is installed, LDtk can execute a command to run this app. But we still need to add the command to LDtk.
- Again, select the LDtk project in Unity to show the importer inspector.
- You will notice an error displayed at the top instructing to configure the project with a custom command.
![Fix Button](../../images/img_Unity_FixTilesetExporter.png)
- From here, there are two ways to add the command to the project: automatically, or manually.
- **Automatic:**
Click the "Fix" button.
A new dialogue will appear.
Ensure all LDtk apps are closed, and click the "Auto-add command" button.
A new dialogue will appear, asking to open the project and save.
Open & save your LDtk project, and you're ready!
- **Manual:**
Click the "Copy" button. This copies the command to the clipboard.
Open the LDtk project, and open the project settings. From there, find the "Custom Commands" area.
Once there, create a new command, paste the command in the field, and change the timing to "Run after saving".
Save your LDtk project, and you're ready!
![Fix Button](../../images/img_ldtk_customCommands.png)
- When saving with a custom command for the first time, LDtk will display a disclaimer. Select "I understand the risks, allow commands".
- If you're in doubt, the code of the app is available **[here](https://github.com/Cammin/LDtkTilesetExporter)**.

After you're ready, drag the project from the project window into the scene or the hierarchy.
![Drag-N-Drop](../../images/gif_DragNDrop.gif)
Tip: Double clicking the LDtk file in the project window will conveniently open the project in LDtk.

# Collision
There are two options to configure collision for the importer.

### Tileset Files
You can configure the physics shape of every individual Tileset tile.
View more information [**here**](../Importer/topic_TilesetImporter.md#sprite-editor)

### IntGrid Files
You can create and add IntGrid Tiles into the importer and configure a collision shape for every IntGrid value, among other things.
View more information [**here**](../Topics/topic_IntGridTile.md#collider-type)
Binary file removed DocFX/documentation/Topics/img.png
Binary file not shown.
4 changes: 2 additions & 2 deletions DocFX/documentation/Topics/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@
- name: Custom Importing
href: topic_CustomImporting.md

- name: Export Native Prefab
href: topic_ExportNativePrefab.md
#- name: Export Native Prefab
#href: topic_ExportNativePrefab.md

- name: Project Settings
href: topic_ProjectSettings.md
Expand Down
4 changes: 1 addition & 3 deletions DocFX/documentation/Topics/topic_IntGridTile.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
# IntGrid Tile
[_**Scripting Reference**_](../../api/LDtkUnity.LDtkIntGridTile.yml)

In the importer's [**IntGrid section**](../Importer/topic_Section_IntGrids.md), you can assign Int Grid Tiles, which has options for tags, layers, custom collision, rendering colors, and GameObjects.

Make some in the [**IntGrid section**](../Importer/topic_Section_IntGrids.md).
In the importer's [**IntGrid section**](../Importer/topic_Section_IntGrids.md), you can create and assign Int Grid Tiles, which has options for tags, layers, custom collision, rendering colors, and GameObjects.

![Level Inspector](../../images/img_Unity_IntGridTile.png)

Expand Down
Binary file added DocFX/images/img_Unity_SpriteEditor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 220cee5

Please sign in to comment.