# TileForm

***

### 1. INTRODUCTION

**TileForm** is a friction-less 3D Level Editor designed for the "Pixel Art in 3D" workflow. It bridges the gap between 2D tilemaps and 3D environments without the overhead of complex modeling suites like Blender or the learning curve of Crocotile3D.

**Philosophy:** TileForm acts as the "Notepad" of 3D modeling. It is instant-on, lightweight (<1MB), and focuses entirely on speed. It allows developers to paint 3D geometry using 2D texture atlases, exporting standard .OBJ or .GLTF files ready for Unity, Godot, and Unreal Engine 5.

***

### 2. SYSTEM REQUIREMENTS & INSTALLATION

#### 2.1 Specifications

* **OS:** Windows 10 or Windows 11 (64-bit recommended).
* **Runtime:** .NET Framework 4.8 (Pre-installed on all modern Windows versions).
* **Dependencies:** None. No installation required.
* **Inputs:** Keyboard + Mouse (3-button mouse recommended).

#### 2.2 Installation

TileForm is **Portable Software**.

1. Unzip the TileForm\_v1.0.zip archive.
2. Place the folder anywhere on your computer.
3. Run TileForm.exe.

> **Note:** On the first run, Windows SmartScreen may flag the application because it is from an indie developer. Click **"More Info" -> "Run Anyway"**.

***

### 3. INTERFACE OVERVIEW

The interface is divided into two primary zones: the **Tool Shelf (Left)** and the **3D Viewport (Right)**.

#### 3.1 The Tool Shelf

* **Project Actions:** Open and Save your .tform work files.
* **Texture Loader:** Imports .png, .jpg, or .bmp tile atlases.
* **Grid Config:** Sets the pixel size of your tiles (e.g., 16px, 32px). TileForm attempts to auto-detect this.
* **Draw Modes:** Switches between **Plane** (flat cards) and **Cube** (solid voxels).
* **Work Plane Indicator:** Displays the current painting axis (Floor, Wall Front, Wall Side).
* **Texture Picker:** A pixel-perfect view of your atlas. Click here to select the tile you want to paint.

#### 3.2 The 3D Viewport

* **Visuals:** Real-time rendering of your level with simple lighting.
* **Cursor:** A semi-transparent "Ghost Block" shows exactly where the next block will be placed and what texture it will use.
* **Camera:** Supports both Orbit (Perspective) and Orthographic (ISO) modes.

***

### 4. CONTROLS CHEATSHEET

<table data-header-hidden><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Context</td><td>Action</td><td>Function</td></tr><tr><td><strong>Movement</strong></td><td>W / A / S / D</td><td>Move the 3D Cursor on the X/Z plane.</td></tr><tr><td><strong>Elevation</strong></td><td>Q / E</td><td>Move the 3D Cursor Up or Down (Y-axis).</td></tr><tr><td><strong>Painting</strong></td><td><strong>Left Click</strong></td><td>Place a block/plane at the cursor.</td></tr><tr><td><strong>Erasing</strong></td><td><strong>Shift + Left Click</strong></td><td>Delete the block at the cursor.</td></tr><tr><td><strong>Camera</strong></td><td><strong>Right Click + Drag</strong></td><td>Orbit/Rotate the camera.</td></tr><tr><td><strong>Panning</strong></td><td><strong>Middle Click + Drag</strong></td><td>Pan the camera view.</td></tr><tr><td><strong>Zoom</strong></td><td><strong>Scroll Wheel</strong></td><td>Zoom in/out.</td></tr><tr><td><strong>Tools</strong></td><td>TAB</td><td><p>Cycle Work Plane (Floor</p><pre><code>        →\to→
</code></pre><p>Wall X</p><pre><code>        →\to→
</code></pre><p>Wall Z.</p></td></tr></tbody></table>

***

### 5. WORKFLOW GUIDE

#### 5.1 Setting Up

1. Click **LOAD ATLAS** and select your tileset image.
2. Check the **GRID (PX)** box. TileForm attempts to guess the size (usually 16 or 32). If your texture looks misaligned, type the correct size here.
3. In the **Texture Picker** (bottom left), click a tile. A **Cyan Box** indicates your selection.

#### 5.2 Painting Modes

TileForm offers two distinct construction methods:

* **Plane Mode (Sprytile Style):**
  * Paints flat, single-sided quads.
  * Use TAB to switch facing direction.
  * Best for: Walls, floors, intricate details, fences, foliage.
* **Cube Mode (Voxel Style):**
  * Paints 6-sided solid cubes.
  * The selected texture is mapped to all 6 faces automatically.
  * Best for: Prototyping, blocking out levels, retro columns/crates.

#### 5.3 Exporting to Game Engines

1. Select your format via the dropdown (.OBJ or .GLTF).
2. Click **EXPORT MODEL**.
3. **Unity/Unreal:** Drag the resulting files into your Content folder.
4. **Godot:** Drag the files into your FileSystem.

> **Pro Tip:** TileForm generates "Non-Destructive" exports. Vertices are not merged aggressively, preserving sharp edges for a low-poly look.

#### 5.4 Project Management (.TFORM)

TileForm saves projects in a lightweight, custom format (.tform).

* **What is saved:** The path to your texture, your grid settings, and the coordinate/UV data of every block.
* **What is NOT saved:** The texture image itself. Do not move or delete your source PNG, or TileForm will ask you to relocate it upon loading.

***

### 6. EXPORT FORMATS EXPLAINED

| Format    | Best For           | Technical Details                                                                                                                               |
| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **.OBJ**  | **Unity / Unreal** | Industry standard geometry. Creates an accompanying .MTL file for material assignments. Supports Z-Flipping for standard coordinate conversion. |
| **.GLTF** | **Godot / Web**    | Modern standard. Embeds binary data. Highly optimized for Godot 4.x.                                                                            |

#### Note on UV Mapping

TileForm employs **Pixel-Perfect UV Locking**.\
To prevent texture bleeding (lines appearing between tiles at a distance), coordinates are calculated at the **mathematical center** of the pixel (Half-Texel Offset). You do not need to add padding to your atlas.

***

### 7. TECHNICAL REFERENCE

#### 1. TECHNOLOGY STACK

TileForm is a **Native Windows Application** built on the **Windows Presentation Foundation (WPF)** framework.

* **Language:** C# 10.0
* **Framework:** .NET Framework 4.8 (Selected for maximum backward compatibility with Windows 10/11 out-of-the-box).
* **Graphics API:** DirectX 9/11 (via WPF Media3D integration).
* **Dependencies:** **Zero.** No external NuGet packages, DLLs, or wrappers. All 3D math, rendering, and file serialization is written from scratch.

#### 2. DATA STRUCTURES & MEMORY

#### 2.1 The World Dictionary

Unlike traditional voxel engines that use 3D Arrays (Block\[,,]), TileForm uses a sparse **Dictionary** approach. This allows for an infinite grid (within integer limits) without pre-allocating memory for empty space.

```
// Key: Coordinate String "X_Y_Z" (Prevents struct hash collisions)
// Value: Block Attributes
private Dictionary<string, BlockData> _world;

public struct BlockData 
{
    public Point3D Pos;   // Spatial Integer Position
    public Axis Ax;       // Orientation (Floor vs Wall X vs Wall Z)
    public DrawMode Mode; // Plane (4 Verts) vs Voxel (24 Verts)
    public double W, H;   // Tile Dimensions ( Multiplier )
    public Rect UV;       // Normalized Texture Coordinates (0.0 - 1.0)
}
  
```

#### 2.2 The Mesh Rebuilding Strategy

TileForm does not utilize a real-time "Game Loop" (Update/Draw). It is entirely **Event-Driven**.

1. **Input Event:** User clicks to place a block.
2. **Data Update:** The BlockData is added to the Dictionary.
3. **Mesh Regeneration:** The entire MeshGeometry3D is cleared and rebuilt from the Dictionary.
4. **Freeze:** The geometry is frozen (mesh.Freeze()) to offload thread safety checks and improve rendering throughput.

Performance profiling indicates this approach remains performant (\~60 FPS) for scenes up to \~10,000 vertices, which covers the target use-case of low-poly level prototyping.

#### 3. COORDINATE SYSTEMS & MAPPING

One of the primary challenges in tool development is the mismatch between UI coordinates, 3D Render coordinates, and Export coordinates.

#### 3.1 Display Coordinate System (WPF)

WPF uses a **Right-Handed Coordinate System** where:

* **+X:** Right
* **+Y:** Up
* **+Z:** Forward (Towards Camera)
* **UV Origin (0,0):** Top-Left

#### 3.2 Texture Sampling Logic

To resolve the discrepancy between standard UV mapping (Bottom-Left origin) and WPF ImageBrushes (Top-Left origin), TileForm employs distinct mapping strategies for Display vs. Export.

* **In-Editor Display:** UVs are mapped directly. V=0 represents the top of the image.
* **OBJ/GLTF Export:** UVs are logically flipped on the V-axis:<br>

  ```
  Vexport = 1.0−Vinternal − Vinternal​*
  ```

#### 3.3 Anti-Bleed Heuristics (Half-Texel Offset)

To prevent texture bleeding (neighboring pixels appearing on edges due to linear filtering), TileForm calculates UVs using a **Half-Texel Offset**.

```
UVstart = PixelStart + 0.5 / TextureWidth      
```

This ensures the GPU samples the exact float-center of the pixel, rather than the border edge.

#### 4. EXPORT PIPELINE

TileForm features two custom-written exporters. They do not rely on Assimp or other libraries.

#### 4.1 OBJ Exporter (Legacy)

Writes ASCII Wavefront .obj files.

* **Optimization:** Does not merge vertices (Non-Destructive). This preserves "Hard Edges" required for the low-poly aesthetic.
* **Material:** Generates a linked .mtl file defining a simple Lambertian material with map\_Kd pointing to the source atlas.
* **Transform:** Z-Axis is inverted during write (v.z = -v.z) to convert from WPF Right-Handed to standard Left-Handed systems (Unity).

#### 4.2 GLTF 2.0 Exporter (Modern)

Writes binary-based GLTF files (.gltf + .bin).

* **JSON Header:** Defines the scene hierarchy, accessors, and PBR material model (pbrMetallicRoughness with roughness 1.0).
* **Binary Buffer:** Vertex Position, Normal, and UV data is written directly to a FileStream as raw bytes (System.Single, IEEE 754).
* **Sampler:** Explicitly defines the Min/Mag filter as 9728 (NEAREST), forcing Game Engines to import the model with "Pixel Art" settings enabled by default.

#### 5. CAMERA MATH

The viewport utilizes a custom Orbit Camera implementation.

#### 5.1 Orbit Logic (Perspective)

Uses Sperical-to-Cartesian conversion to orbit a focal point.\
x = sin⁡(θ)×cos⁡(ϕ) × Radius

y = sin⁡(ϕ) × Radius

z = cos⁡(θ) × cos⁡(ϕ) × Radius

#### 5.2 Panning Logic

Panning in 3D perspective requires calculating the Camera's Local Axis relative to the World Up vector.

1. **Right Vector:** Cross Product of Up (0,1,0) and LookDirection.
2. **Pan:** The focal point is translated along this Right vector (X) and the World Up vector (Y).

#### 6. KNOWN LIMITATIONS

* **Vertex Limit:** WPF MeshGeometry3D uses Int32 for indices, but performance degrades before hitting the 2 billion vertex limit. Recommended for scenes < 5,000 blocks.
* **Texture Formats:** Supports only formats natively decoded by Windows Imaging Component (PNG, JPEG, BMP, TIFF, GIF).
* **Lighting:** Lighting is calculated per-vertex by WPF. Since blocks share vertices in Voxel mode, lighting is smooth. Users desiring flat shading should rely on the game engine import settings (Recalculate Normals / Flat Shade).

***

### 8. CREATIVE RIGHTS & LICENSE

**Software License:**\
The TileForm.exe software is proprietary. You may not reverse engineer, decompile, or resell the software itself.

**Artistic License:**\
You own 100% of the files (.obj, .gltf, .tform) created with this tool. You are free to use them in commercial projects, games, and art without attribution (though attribution to GregOrigin is appreciated).

***

### 9. TROUBLESHOOTING

**Q: My texture looks blurry in the app.**\
**A:** TileForm forces "Nearest Neighbor" rendering. If it looks blurry, check your Windows Display Scale settings, or ensure your source PNG is actually pixel art.

**Q: I can't move the cursor.**\
**A:** Ensure the window is focused (click the 3D view once). Use WASD.

**Q: The export is invisible in my Game Engine.**\
**A:**

1. Check the scale (TileForm uses 1 Unit = 1 Block).
2. Check the material. If the .png moved relative to the model, you may need to re-assign the texture in your engine.
3. (Unity/Godot) Ensure your texture Import Settings are set to **"Filter Mode: Point / Nearest"** to match the look.

**(c) 2025**[ **Andras Gregori**](https://linktr.ee/agregori) **@** [**GregOrigin LLC**](https://www.gregorigin.com)**.**