ChrisTutorials

README.md Grid Building for Godot

Feb 23rd, 2025 (edited)
479
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 6.86 KB | None | 0 0
  1. # GridBuilding Plugin for Godot 4.3+
  2.  
  3. A building and targeting system for 2D Godot games using **TileMapLayer** nodes.
  4.  
  5. ## Requirements
  6. - Godot 4.3 or newer
  7.  
  8. ## Resources
  9. - **Tutorials:** [YouTube Playlist](https://www.youtube.com/playlist?list=PLyH-qXFkNSxl5bQkTYzMXyRwVr8Vc4Sib)
  10. - **Devlog Updates:** [Itch.io Devlog](https://itch.io/dashboard/game/2117450/devlog)
  11. - **Support:** Join the discord (link provided on purchase & in the plugin README files)
  12.  
  13. ---
  14.  
  15. ## Important Usage Tips
  16. - Use the `templates` folder to quickly add systems and the **GridPositioner** stack to your scene. Customize systems or states as needed later.
  17. - Add **UserAssigner** to your player and **GridNodeAssigner** to your level/world to assign runtime nodes to system states.
  18. - For scene design, enable grid snapping with an offset (e.g., 8x8 for 16x16 tiles) to preview collision lines.
  19. - Check the demo project for examples of integrating systems and resources.
  20.  
  21. ---
  22.  
  23. ## How the System Works
  24.  
  25. ### Core Components
  26. - **BuildingSystem:** Shows previews without collision and places objects if placement is valid.
  27. - **PlacementValidator:** Tests defined rules to ensure placement validity across all tiles under an object.
  28. - **RuleCheckIndicatorManager:** Creates indicators for each tile under an object based on **TileCheckRules**, showing validity.
  29. - **ManipulationSystem:** Manages rotating, flipping, moving, and demolishing objects in the scene.
  30. - **GridTargetingSystem:** Aligns object targeting with the grid, moving indicators accordingly.
  31. - **GridTargetingState:** Updates the **GridPositioner** for tile-snapped positioning based on mouse movement.
  32. - **ManipulationParent:** Applies transforms (e.g., rotation, flipping) to selected objects and indicators.
  33.  
  34. ### Integration
  35. State resources connect these systems with node references and signals. Use **UserAssigner** (on the player) and **GridStateAssigner** (on the level/world) to set references at runtime. See the demo for examples (Top-Down 2D, Platformer, Isometric).
  36.  
  37. ---
  38.  
  39. ## Quick Start Guide
  40. 1. **Backup Your Project:** Disable any old plugin in *Project Settings > Plugins*, remove the旧 `grid_builder` folder, and unzip the new plugin into `addons/grid_building`.
  41. 2. **Enable Plugin:** Activate it in *Project Settings > Plugins*.
  42. 3. **Add Templates:** Import `templates/systems.tscn` into your main scene (make it local to edit).
  43. 4. **Add Grid Stack:** Include `grid_positioner_stack.tscn` and set its collision mask to your target layer.
  44. 5. **Isometric Setup:** For isometric games, adjust the **RuleCheckIndicatorManager**’s template to `rule_check_indicator_isometric` and resize as needed.
  45. 6. **Set Runtime Nodes:** Add **UserAssigner** to your player and **GridStateAssigner** to your level, then assign nodes in the Inspector.
  46. 7. **Enable Build Mode:** Create a **Placeable** resource and use `set_buildable_preview()` on **BuildingSystem**. Or, add `placeable_selection_ui.tscn` to your UI, setting **BuildingState** and **ModeState**.
  47. 8. **Create Placeable:** In a new folder, make a **Placeable** resource, set its `scene_path` to a **PackedScene**, and add a tag/name/icon.
  48. 9. **Link UI:** Create a **CategoricalTag**, assign it to the **Placeable** and **PlaceableSelectionUI**, and add the **Placeable** to the UI’s array.
  49. 10. **Test UI:** Enable "Show at Start" on **PlaceableSelectionUI** or set an "Open Action" (e.g., "B") in *Project Settings > Input Map*.
  50. 11. **Design Scene:** Assign a 2D `.tscn` file (e.g., a building) to the **Placeable**’s `packed_scene`.
  51. 12. **Run Scene:** Launch with **BuildingSystem**, **GridTargetingSystem**, and **ManipulationSystem**. Use the UI to select and place objects (default build key: Enter).
  52. 13. **Make Manipulatable:** Add a **Manipulatable** node to an object’s scene, set its root, and configure **ManipulatableSettings** for move/rotate/flip/demolish options.
  53.  
  54. ---
  55.  
  56. ## Building Rules
  57. Rules restrict placement and are set in two places:
  58. - **BuildingSystem > PlacementValidator > Base Rules** (global rules).
  59. - **Placeable > Placement Rules** (per-object rules).
  60.  
  61. All rules must pass for placement. Use `build_log.tscn` in your UI (with **BuildingState**) to debug rule results (`RuleResult.new(success, reason)`).
  62.  
  63. ### Included Rules
  64. - **CollisionCheckRule:** Passes/fails based on collisions and `pass_on_collision`.
  65. - **SpendMaterialsRuleGeneric:** Spends resources from any inventory (inherit **VirtualItemContainer** for compatibility).
  66. - **WithinTilemapBoundsRule:** Ensures indicators cover valid **TileMap** tiles.
  67. - **ValidPlacementTileRule:** Verifies tile data (e.g., "buildable" custom field).
  68.  
  69. ### Custom Rules
  70. Inherit **PlacementRule** or **TileCheckRule**, then override `setup()`, `validate_condition()`, and `tear_down()`. See `building_rule.gd` for method details.
  71.  
  72. ---
  73.  
  74. ## Manipulating Objects
  75. Add a **Manipulatable** node to an object’s scene, set its root, and configure **ManipulatableSettings** for move, rotate, flip, or demolish options.
  76.  
  77. ### Overlapping Source Objects
  78. To move an object over its original position:
  79. - In **ManipulationSystem > ManipulationSettings**, enable "Disable Layer in Manipulation" and set "Disabled Physics Layer" to the source’s layer.
  80. - Example: See `demo_top_down.tscn`.
  81.  
  82. ---
  83.  
  84. ## Key Classes
  85. - **Placeable:** Resource defining an object for placement, including its **PackedScene** and optional rules.
  86. - **BuildingSystem:** Manages previews and placement, relying on **GridTargetingSystem** and **RuleCheckIndicator**.
  87. - **GridTargetingSystem:** Converts mouse position to tile coordinates.
  88. - **PlacementRule:** Base for rules blocking placement if conditions fail.
  89.  
  90. ---
  91.  
  92. ## Inventory (Optional Addon)
  93. Install at `addons/grid_building_inventory/`:
  94. - **ItemContainer:** Stores **BaseItemStacks** with tag filtering.
  95. - **BaseItemStack:** Holds a **BaseItem** and count.
  96. - **BaseItem:** Base resource for items (inherit for **SpendMaterialsRule**).
  97. - **SpendMaterialsRule:** Checks **ItemContainer** for required items.
  98.  
  99. ---
  100.  
  101. ## Categorical Tags
  102. - **CategoricalTag:** Resource with `display_name` and `icon` for categorizing **Placeable** or **BaseItem**. Store in separate folders (e.g., `placeable_tags/`).
  103.  
  104. ---
  105.  
  106. ## Optional Components
  107. Add these under your main systems (see demo):
  108. - **TileMapBuildingOverlay:** Overlays a tile during build mode (set via **TileSet** Atlas ID). [More Info](https://chris-tutorials.itch.io/grid-building-godot/devlog/630838/320-isometric-tilemap-support)
  109. - **TargetHighlighter:** Tints targets (green for valid, red for invalid).
  110. - **CursorChanger:** Updates cursor based on mode.
  111.  
  112. ---
  113.  
  114. ## Asset Credits
  115. See credits: [Pastebin](https://pastebin.com/HYznA3F8)
  116.  
  117. ---
  118.  
  119. ## FAQ
  120. **Q: Why do targeting/preview disappear when hovering over UI?**
  121. **A:** Set UI nodes’ *Mouse > Filter* to "Pass" or "Ignore." Or, uncheck "Hide On Handled" in **TargetingSettings** to always show the preview.
  122.  
  123. ---
Advertisement
Add Comment
Please, Sign In to add comment