update tilemap docs

Author: CodedRedGIT

docs/guide/tilemaps.mdx

@@ -5,7 +5,7 @@ title: Tilemaps
 
 # Tilemaps
 
-Tilemaps let you paint 2D levels quickly using a tileset (a grid of sprites).  
+Tilemaps let you paint 2D levels quickly using a tileset (a grid of sprites) or colored-square tiles.  
 A **Tilemap** entity is a regular entity, so you can move, scale, parent,  
 and duplicate it like anything else.
 
@@ -30,7 +30,6 @@ and duplicate it like anything else.
 
 Need procedural generation or an in-game brush?  
 Just cast your entity as a Tilemap and call its helper methods.
-
 ```ts
 import { Behavior, Rng, syncedValue, Tilemap } from "@dreamlab/engine";
 
@@ -47,10 +46,9 @@ export default class Generate extends Behavior {
   seed: number = 0;
 
   /** Grass‑only palette IDs. */
-  static readonly #GRASS = [1,2,3,8,9,10,11,16,17,18,19,24,25,26,27] as const;
+  static readonly #GRASS = [1, 2, 3, 8, 9, 10, 11, 16, 17, 18, 19, 24, 25, 26, 27] as const;
   /** Flower‑only palette IDs. */
-  static readonly #FLOWER = [4,5,6,7,12,13,14,20,21,22,23,28,29,30,31] as const;
-
+  static readonly #FLOWER = [4, 5, 6, 7, 12, 13, 14, 20, 21, 22, 23, 28, 29, 30, 31] as const;
 
   /** Deterministic RNG tied to `seed`. */
   #prng!: () => number;
@@ -64,9 +62,9 @@ export default class Generate extends Behavior {
     const roll = this.#prng(); // 0 … 1
     if (roll < 0.05) return 0; // empty
     if (roll < 0.8) { // grass
-      return sampleArray(Generate.#GRASS_TILES, this.#prng);
+      return sampleArray(Generate.#GRASS, this.#prng);
     }
-    return sampleArray(Generate.#FLOWER_TILES, this.#prng);
+    return sampleArray(Generate.#FLOWER, this.#prng);
   }
 
   clearData(): void {
@@ -102,48 +100,80 @@ export default class Generate extends Behavior {
     const right = this.inputs.getKey("MouseRight");
     if (!left && !right) return;
 
-    const tile = this.#tilemap.getTileAtPoint(world);
+    const tile = this.#tilemap.getTileCoordinatesAtPoint(world);
     if (!tile) return;
 
     const id = left ? 33 /* hard‑coded brush */ : this.#getTile();
     this.#tilemap.setTile(tile.x, tile.y, id);
   }
 }
 ```
-
 ---
 
-## Core API
+## Example — Colored Square Tilemap
 
-| Method                                   | Purpose                                                     |
-|------------------------------------------|-------------------------------------------------------------|
-| `getTile(x, y)`                          | Returns `TileData` \| `undefined` for that coordinate.      |
-| `getTilePaletteId(x, y)`                 | Returns palette index (`number`) or `undefined`.            |
-| `setTile(x, y, paletteId?)`              | Sets tile; pass `undefined` to erase.                       |
-| `getTileAtPoint(worldPos)`               | Ray-casts the cursor; returns `{ x, y, …tile }` or `undefined`. |
-| `clearTiles()`                           | Removes every tile from the map.                            |
-| `tiles()`                                | Generator that yields `{ x, y, tile }` for each filled cell.|
-| `bounds` *(getter)*                      | `{ width, height, offset }` in tile units.                  |
+If you want a simple colored checkerboard pattern instead of an atlas,  
+you can set per-tile colors:
+```ts
+import { Behavior, Tilemap } from "@dreamlab/engine";
 
-### `TileData` union
+export default class Checkerboard extends Behavior {
+  #tm = this.entity.cast(Tilemap);
+
+  static readonly WHITE = 0xffffff;
+  static readonly GREY = 0xcccccc;
+  static readonly N = 256;
+
+  #fill(): void {
+    this.#tm.clearTiles();
+    for (let y = 0; y < Checkerboard.N; y++) {
+      for (let x = 0; x < Checkerboard.N; x++) {
+        const color = ((x + y) & 1) === 0 ? Checkerboard.WHITE : Checkerboard.GREY;
+        this.#tm.setColor(x, y, color);
+      }
+    }
+  }
+
+  onInitialize(): void {
+    if (this.game.isServer()) this.#fill();
+  }
+}
+```
+---
+
+## Core API
 
+| Method                                         | Purpose |
+|-----------------------------------------------|---------|
+| `getTile(x, y)`                               | Get atlas tile ID at `(x, y)`, or `undefined`. |
+| `setTile(x, y, atlasId?)`                     | Set atlas tile ID; pass `undefined` to erase. |
+| `setTiles(xs[], ys[], atlasIds[])`            | Set multiple atlas tiles at once. |
+| `getColor(x, y)`                              | Get solid color at `(x, y)`, or `undefined`. |
+| `setColor(x, y, color?)`                      | Set solid color; pass `undefined` to erase. |
+| `getTileInfo(x, y)`                           | Get `TileInfo` (either `{ type: "atlas", id }` or `{ type: "color", color }`). |
+| `setTileInfo(x, y, info?)`                    | Set a full `TileInfo` object. |
+| `getTileCoordinatesAtPoint(worldPos)`         | Convert world coordinates to tile `(x, y)`. |
+| `clearTile(x, y)`                             | Remove any tile (atlas or color) at `(x, y)`. |
+| `clearTiles()`                                | Remove all tiles. |
+| `tiles()`                                     | Iterate all filled tiles. |
+| `bounds` *(getter)*                           | `{ width, height, offset }` in tile units. |
+
+### `TileInfo` union
 ```ts
-type TileData =
-  | { type: "color";        color: string; alpha?: number }
-  | { type: "texture";      texture: string }
-  | { type: "spritesheet";  spritesheet: string; frame: number }
-  | { type: "texture-slice"; texture: string; x: number; y: number };
+type TileInfo =
+  | { type: "atlas"; id: number }
+  | { type: "color"; color: number };
 ```
 
 ---
 
 ### FAQ
 
 **How big can a tilemap be?**  
-Technically unlimited, but performance is tuned for ≤ 10 000 drawn tiles.
+Technically unlimited, but performance is optimized for ≤ 20 million drawn tiles (similar to large Terraria worlds).
 
 **Can I swap atlases at runtime?**  
-Yes — just assign a new path to **Atlas**; all visuals update automatically.
+Yes — assign a new path to **Atlas**; visuals update automatically.
 
 **How do I force pixel-perfect textures?**  
-Set **Scale filter mode** to “nearest” on the Tilemap *or* on the Camera.
+Set **Scale filter mode** to "nearest" on the Tilemap *or* Camera.