@modastar/godot-skills 0.1.5 → 0.2.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "godot-skills",
   "displayName": "godot-skills",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Make your coding agent write modern Godot 4.7+ best practices — lightweight and token-efficient.",
   "keywords": ["godot", "gdscript", "gdshader", "agent-skills"]
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "godot-skills",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Make your coding agent write modern Godot 4.7+ best practices — lightweight and token-efficient.",
   "keywords": ["godot", "gdscript", "gdshader", "agent-skills"],
   "skills": "./skills/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modastar/godot-skills",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Make your coding agent write modern Godot 4.7+ best practices — lightweight and token-efficient.",
   "keywords": [
     "pi-package",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "godot-skills",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Make your coding agent write modern Godot 4.7+ best practices — lightweight and token-efficient."
 }

package/skills/godot-tilemap-2d/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: godot-tilemap-2d
+description: "Write, edit, or debug Godot 2D tile maps: TileMapLayer, deprecated TileMap, set_cell, tile custom data, terrains, and tile collision."
+---
+
+# TileMap 2D
+
+Target Godot 4.7+.
+
+## TileMapLayer, never TileMap
+
+- `TileMap` is deprecated since 4.3. Use one `TileMapLayer` per layer; layer index parameters no longer exist. Convert old scenes from the TileMap bottom panel → toolbox icon → *Extract TileMap layers as individual TileMapLayer nodes*.
+- Every layer needs a `tile_set`; sibling layers normally share one `TileSet` resource.
+- Cell coordinates serialize as 16-bit signed ints; X and Y outside `-32768..32767` wrap on save.
+
+## Cells
+
+```gdscript
+@onready var ground: TileMapLayer = $Ground
+
+ground.set_cell(Vector2i(3, 5), source_id, Vector2i(0, 0))  # coords first, no layer arg
+ground.erase_cell(Vector2i(3, 5))
+```
+
+- `set_cell(coords, source_id = -1, atlas_coords = Vector2i(-1, -1), alternative_tile = 0)`. Any of `source_id = -1`, `atlas_coords = Vector2i(-1, -1)`, or `alternative_tile = -1` erases the cell and resets all three identifiers.
+- `alternative_tile` defaults to `0` in `set_cell()` but to `-1` in `get_used_cells_by_id()`, where it means "any".
+- With a `TileSetScenesCollectionSource`, `atlas_coords` must be `Vector2i(0, 0)` and `alternative_tile` is the scene id.
+- Flip and rotation are bit flags packed into `alternative_tile`, not properties:
+  ```gdscript
+  const ROTATE_90 := TileSetAtlasSource.TRANSFORM_TRANSPOSE | TileSetAtlasSource.TRANSFORM_FLIP_H
+  ground.set_cell(coords, source_id, atlas_coords, alt | ROTATE_90)
+  ```
+  Read back with `is_cell_flipped_h()`, `is_cell_flipped_v()`, `is_cell_transposed()` (atlas sources only).
+- Use `get_neighbor_cell(coords, TileSet.CELL_NEIGHBOR_*)` instead of adding `Vector2i(1, 0)`; only it is correct for hex and isometric layouts.
+
+## Coordinates
+
+- `local_to_map()` and `map_to_local()` use the layer's **local** space: `local_to_map(to_local(body.global_position))`, or `local_to_map(get_local_mouse_position())`.
+- `map_to_local()` returns the tile center, not its corner.
+
+## Per-tile data
+
+```gdscript
+var data := ground.get_cell_tile_data(ground.local_to_map(ground.get_local_mouse_position()))
+if data:
+    var power: Variant = data.get_custom_data("power")
+```
+
+- `get_cell_tile_data()` returns `null` for empty cells and non-atlas sources — always null-check.
+- `TileData` is read-only at runtime except inside `_tile_data_runtime_update()`.
+
+## Terrains
+
+`set_cells_terrain_connect(cells, terrain_set, terrain, ignore_empty_terrains = true)` joins matching neighbors and may rewrite adjacent tiles; `set_cells_terrain_path()` follows cell order for roads and rivers. Both are expensive — pass the whole array in one call, never cell by cell.
+
+## Collision and navigation
+
+- Shapes come from the `TileSet` physics layers; toggle with `collision_enabled`, inspect with `collision_visibility_mode`. Same pattern for `navigation_enabled` and `occlusion_enabled`.
+- Set `use_kinematic_bodies = true` only for layers that move (moving platforms).
+- `physics_quadrant_size` (default 16) merges similar tiles' shapes per quadrant, so a collider covers many cells. Recover the tile with `get_coords_for_body_rid(rid)`, passing `KinematicCollision2D.get_collider_rid()`.
+- Call `set_navigation_map()` to keep a layer's navigation separate from other layers.
+
+## Updates and ordering
+
+- Cell edits are batched to the end of the frame, so scene tiles from a `TileSetScenesCollectionSource` initialize *after* their parent and derived state read right after `set_cell()` can be stale. `update_internals()` forces an update — expensive, never per cell in a loop.
+- The `changed` signal fires very often during batch edits; defer real work with `call_deferred()`.
+- For runtime visual overrides implement `_use_tile_data_runtime_update(coords) -> bool` and `_tile_data_runtime_update(coords, tile_data)`, then call `notify_runtime_tile_data_update()` when the predicate's result changes. Returning `true` broadly is a significant performance cost.
+- Top-down depth: enable `y_sort_enabled` (from `CanvasItem`) and shift the layer with `y_sort_origin`. `x_draw_order_reversed` applies only while Y-sorting.