first commit
This commit is contained in:
@@ -0,0 +1,350 @@
|
||||
# EnhancedGridMap Plugin for Godot 4.3
|
||||
|
||||
## Overview
|
||||
|
||||
EnhancedGridMap is a powerful plugin for Godot 4.3 that extends the functionality of the built-in GridMap node. It provides additional features for grid-based game development, including custom cell states, A* pathfinding, and an intuitive editor interface.
|
||||
|
||||
## Features
|
||||
|
||||
- Custom grid size (columns and rows)
|
||||
- Auto-generation of grid
|
||||
- Custom cell states with visual representation
|
||||
- A* pathfinding with diagonal movement option
|
||||
- Randomization of grid cells
|
||||
- Fill grid with specific cell types
|
||||
- Editor dock for easy manipulation of grid properties
|
||||
|
||||
## Installation
|
||||
|
||||
1. Copy the `enhanced_gridmap` folder into your Godot project's `addons` directory.
|
||||
2. Enable the plugin in Project Settings > Plugins.
|
||||
|
||||
## EnhancedGridMap Dock
|
||||
|
||||
The EnhancedGridMap Dock provides a user-friendly interface to control and manipulate the EnhancedGridMap node. Here's a detailed explanation of all features available in the dock:
|
||||
|
||||
### Grid Properties
|
||||
|
||||
1. **Columns**: Set the number of columns in the grid.
|
||||
2. **Rows**: Set the number of rows in the grid.
|
||||
3. **Auto Generate**: Toggle automatic grid generation when properties change.
|
||||
|
||||
### Grid Operations
|
||||
|
||||
1. **Generate**: Manually generate the grid based on current properties.
|
||||
2. **Clear**: Remove all cells from the grid.
|
||||
3. **Randomize**: Randomly assign cell types based on defined states.
|
||||
4. **Fill**: Fill the entire grid with a specific cell type.
|
||||
|
||||
### Cell States
|
||||
|
||||
The dock allows you to define and manage custom cell states:
|
||||
|
||||
1. **Default States**:
|
||||
- Normal
|
||||
- Hover
|
||||
- Start
|
||||
- End
|
||||
- Non-Walkable
|
||||
|
||||
2. **Custom States**:
|
||||
- Add new states with the "Add Item State" button.
|
||||
- For each state, you can set:
|
||||
- Name
|
||||
- ID (used in scripts to reference the state)
|
||||
- Include in Randomize (toggle)
|
||||
- Randomize Percentage (when included in randomization)
|
||||
|
||||
3. **State Management**:
|
||||
- Edit existing states
|
||||
- Remove custom states
|
||||
|
||||
### A* Pathfinding
|
||||
|
||||
1. **Start Position**: Set the X and Z coordinates for the pathfinding start point.
|
||||
2. **End Position**: Set the X and Z coordinates for the pathfinding end point.
|
||||
3. **Find Path**: Calculate and visualize the path between start and end points.
|
||||
4. **Diagonal Movement**: Toggle to allow diagonal movement in pathfinding.
|
||||
|
||||
### Visual Grid Editor
|
||||
|
||||
The dock includes a visual representation of the grid:
|
||||
|
||||
1. Each cell displays its coordinates.
|
||||
2. Drop-down menus in each cell allow you to change the cell's state directly.
|
||||
|
||||
## In-Depth Feature Explanation
|
||||
|
||||
### Custom Grid Generation
|
||||
|
||||
The EnhancedGridMap allows for flexible grid generation:
|
||||
|
||||
1. **Auto-generation**: The grid can automatically update when properties change.
|
||||
2. **Manual generation**: Use the `generate_grid()` method for custom generation logic.
|
||||
3. **Clear and regenerate**: Useful for level resets or procedural generation.
|
||||
|
||||
### Cell States
|
||||
|
||||
Cell states are central to the EnhancedGridMap's functionality:
|
||||
|
||||
1. **Default states**: Predefined states for common use cases (normal, hover, start, end, non-walkable).
|
||||
2. **Custom states**: Create states for specific game mechanics (e.g., water, lava, ice).
|
||||
3. **State properties**:
|
||||
- ID: Used in scripts to set or check cell states.
|
||||
- Randomize inclusion: Determine if the state should be included in randomization.
|
||||
- Randomize percentage: Control the frequency of the state when randomizing.
|
||||
|
||||
### A* Pathfinding
|
||||
|
||||
The integrated A* pathfinding system offers:
|
||||
|
||||
1. **Efficient pathfinding**: Quickly find optimal paths between two points.
|
||||
2. **Diagonal movement**: Option to allow or disallow diagonal movement.
|
||||
3. **Custom cost functions**: Override `get_cell_cost()` for complex movement rules.
|
||||
4. **Path visualization**: Easily visualize calculated paths for debugging.
|
||||
|
||||
### Grid Manipulation
|
||||
|
||||
Several methods for manipulating the grid:
|
||||
|
||||
1. **`set_cell_from_data(x, z, item_index)`**: Set a specific cell's state.
|
||||
2. **`fill_grid(item_index)`**: Fill the entire grid with a specific state.
|
||||
3. **`randomize_grid()`**: Randomly assign states based on defined probabilities.
|
||||
4. **`randomize_grid_custom(randomize_states)`**: Use custom randomization rules.
|
||||
|
||||
### Extending Functionality
|
||||
|
||||
The EnhancedGridMap is designed to be easily extended:
|
||||
|
||||
1. **Custom grid generation**: Override `generate_grid()` for specialized layouts.
|
||||
2. **Custom pathfinding costs**: Implement `get_cell_cost()` for complex movement rules.
|
||||
3. **Integration with game mechanics**: Use signals like `grid_updated` to trigger game events.
|
||||
|
||||
### Editor Integration
|
||||
|
||||
The plugin seamlessly integrates with the Godot editor:
|
||||
|
||||
1. **Visual editing**: Manipulate the grid directly in the editor viewport.
|
||||
2. **Real-time updates**: Changes in the dock immediately reflect in the scene.
|
||||
3. **Custom inspector**: The EnhancedGridMap node has a custom inspector for easy property editing.
|
||||
|
||||
## Plugin Usage
|
||||
|
||||
### Basic Setup
|
||||
|
||||
1. Add an `EnhancedGridMap` node to your scene.
|
||||
2. Assign a `MeshLibrary` to the `EnhancedGridMap`.
|
||||
3. Use the `EnhancedGridMap` dock in the editor to configure grid properties and cell states.
|
||||
|
||||
### Scripting
|
||||
|
||||
You can also interact with the `EnhancedGridMap` through GDScript. Here's a basic example:
|
||||
|
||||
```gdscript
|
||||
var enhanced_gridmap = $EnhancedGridMap
|
||||
|
||||
# Generate a 10x10 grid
|
||||
enhanced_gridmap.columns = 10
|
||||
enhanced_gridmap.rows = 10
|
||||
enhanced_gridmap.generate_grid()
|
||||
|
||||
# Find a path from (0,0) to (5,5)
|
||||
var path = enhanced_gridmap.find_path(Vector2(0, 0), Vector2(5, 5))
|
||||
```
|
||||
|
||||
## Sample Scene and Player Movement
|
||||
|
||||
The plugin includes a sample scene that demonstrates how to implement player movement using the EnhancedGridMap. This scene showcases pathfinding and grid-based movement.
|
||||
|
||||
### Scene Setup
|
||||
|
||||
The sample scene (`main.tscn`) includes:
|
||||
|
||||
1. An `EnhancedGridMap` node with a pre-configured grid.
|
||||
2. A player character `CharacterBody3D` with a custom script for grid-based movement.
|
||||
3. A top-down camera for easy visualization.
|
||||
|
||||
### Player Movement Script
|
||||
|
||||
The `player.gd` script provides a flexible implementation of grid-based movement using the EnhancedGridMap. Key features include:
|
||||
|
||||
- Click-to-move functionality
|
||||
- Pathfinding using the EnhancedGridMap's A* algorithm
|
||||
- Smooth movement along the calculated path
|
||||
- Customizable cell size and offset
|
||||
- Option for diagonal movement
|
||||
|
||||
### Usage Example
|
||||
|
||||
To use the player movement script in your own scene:
|
||||
|
||||
1. Add an `EnhancedGridMap` to your scene.
|
||||
2. Add a `CharacterBody3D` (or other suitable node) for your player.
|
||||
3. Attach the `player.gd` script to your player node.
|
||||
4. Set the `enhanced_gridmap_path` and `player_path` in the inspector.
|
||||
5. Customize other properties like `cell_size` and `use_diagonal_movement` as needed.
|
||||
|
||||
Here's a minimal setup example:
|
||||
|
||||
```gdscript
|
||||
extends Node3D
|
||||
|
||||
@onready var enhanced_gridmap = $EnhancedGridMap
|
||||
@onready var player = $Player
|
||||
|
||||
func _ready():
|
||||
player.enhanced_gridmap_path = enhanced_gridmap.get_path()
|
||||
player.player_path = player.get_path()
|
||||
player.cell_size = Vector3(2, 2, 2)
|
||||
player.use_diagonal_movement = true
|
||||
```
|
||||
|
||||
This setup allows for click-to-move functionality on your EnhancedGridMap, with the player finding and following optimal paths while avoiding non-walkable cells.
|
||||
|
||||
## API Reference
|
||||
|
||||
### Properties
|
||||
|
||||
- `columns: int` - Number of columns in the grid
|
||||
- `rows: int` - Number of rows in the grid
|
||||
- `auto_generate: bool` - Whether to automatically generate the grid when properties change
|
||||
- `normal_item: int` - Item index for normal cells
|
||||
- `hover_item: int` - Item index for hover state cells
|
||||
- `start_item: int` - Item index for pathfinding start cells
|
||||
- `end_item: int` - Item index for pathfinding end cells
|
||||
- `non_walkable_item: int` - Item index for non-walkable cells
|
||||
- `diagonal_movement: bool` - Whether to allow diagonal movement in pathfinding
|
||||
|
||||
### Methods
|
||||
|
||||
#### Grid Management
|
||||
|
||||
- `generate_grid()` - Generate the grid based on current properties
|
||||
- `clear_grid()` - Clear all cells in the grid
|
||||
- `randomize_grid()` - Randomize cell types in the grid
|
||||
- `randomize_grid_custom(randomize_states: Array)` - Randomize cell types based on custom states
|
||||
- `fill_grid(item_index: int)` - Fill the entire grid with a specific item type
|
||||
|
||||
#### Cell Manipulation
|
||||
|
||||
- `set_cell_from_data(x: int, z: int, item_index: int)` - Set a specific cell's item type
|
||||
- `get_cell_cost(x: int, z: int) -> float` - Get the cost of moving through a specific cell
|
||||
|
||||
#### Pathfinding
|
||||
|
||||
- `find_path(start: Vector2, end: Vector2) -> Array` - Find a path between two points
|
||||
- `set_diagonal_movement(enable: bool)` - Enable or disable diagonal movement in pathfinding
|
||||
- `set_point_solid(x: int, z: int, is_solid: bool)` - Set whether a point is solid (non-walkable) for pathfinding
|
||||
|
||||
### Signals
|
||||
|
||||
- `mesh_library_changed` - Emitted when the MeshLibrary is changed
|
||||
- `grid_updated` - Emitted when the grid is updated
|
||||
|
||||
### Example Scene : Player Movement API
|
||||
|
||||
Here are the main properties and methods of the player movement script:
|
||||
|
||||
#### Properties
|
||||
|
||||
- `enhanced_gridmap_path: NodePath` - Path to the EnhancedGridMap node
|
||||
- `player_path: NodePath` - Path to the player node
|
||||
- `cell_size: Vector3` - Size of each grid cell
|
||||
- `cell_offset: Vector3` - Offset applied to the player's position
|
||||
- `center_x: bool` - Center the player horizontally within the cell
|
||||
- `center_y: bool` - Center the player vertically within the cell
|
||||
- `center_z: bool` - Center the player depth-wise within the cell
|
||||
- `use_diagonal_movement: bool` - Allow diagonal movement in pathfinding
|
||||
|
||||
#### Methods
|
||||
|
||||
- `find_valid_starting_position() -> Vector2i` - Find a valid starting position on the grid
|
||||
- `move_player_to_clicked_position(grid_position: Vector2i)` - Move the player to a clicked grid position
|
||||
- `move_player_along_path(path: Array)` - Move the player along a calculated path
|
||||
- `update_player_position(grid_position: Vector2i)` - Update the player's position based on a grid position
|
||||
- `grid_to_world(grid_position: Vector2i) -> Vector3` - Convert a grid position to a world position
|
||||
|
||||
## Extending the Plugin
|
||||
|
||||
### Custom Item States
|
||||
|
||||
You can add custom item states to the EnhancedGridMap:
|
||||
|
||||
1. In the `EnhancedGridMap` dock, click the "Add Item State" button.
|
||||
2. Set a name, ID, and randomization properties for the new state.
|
||||
3. Use the new state's ID when setting cell types in your scripts.
|
||||
|
||||
### Custom Pathfinding Costs
|
||||
|
||||
Override the `get_cell_cost` method in a script extending EnhancedGridMap to implement custom pathfinding costs:
|
||||
|
||||
```gdscript
|
||||
extends EnhancedGridMap
|
||||
|
||||
func get_cell_cost(x: int, z: int) -> float:
|
||||
var cell_item = get_cell_item(Vector3i(x, 0, z))
|
||||
match cell_item:
|
||||
0: return 1.0 # Normal cell
|
||||
1: return 2.0 # Slow terrain
|
||||
2: return 0.5 # Fast terrain
|
||||
_: return INF # Non-walkable
|
||||
```
|
||||
|
||||
### Custom Grid Generation
|
||||
|
||||
You can implement custom grid generation by overriding the `generate_grid` method:
|
||||
|
||||
```gdscript
|
||||
extends EnhancedGridMap
|
||||
|
||||
func generate_grid():
|
||||
clear()
|
||||
for x in range(columns):
|
||||
for z in range(rows):
|
||||
var item_index = (x + z) % 2 # Checkerboard pattern
|
||||
set_cell_item(Vector3i(x, 0, z), item_index)
|
||||
update_grid_data()
|
||||
initialize_astar()
|
||||
update_astar_costs()
|
||||
```
|
||||
|
||||
## Extending the Player Movement
|
||||
|
||||
You can extend the player movement functionality by overriding or adding methods to the `player.gd` script. For example:
|
||||
|
||||
### Custom Movement Rules
|
||||
|
||||
```gdscript
|
||||
extends "res://addons/enhanced_gridmap/examples/player.gd"
|
||||
|
||||
func is_valid_move(from: Vector2i, to: Vector2i) -> bool:
|
||||
# Add custom logic for valid moves
|
||||
var distance = from.distance_to(to)
|
||||
return distance <= 1 and super.is_valid_move(from, to)
|
||||
```
|
||||
|
||||
### Additional Interactions
|
||||
|
||||
```gdscript
|
||||
extends "res://addons/enhanced_gridmap/examples/player.gd"
|
||||
|
||||
func _unhandled_input(event):
|
||||
super._unhandled_input(event)
|
||||
|
||||
if event.is_action_pressed("interact"):
|
||||
interact_with_current_cell()
|
||||
|
||||
func interact_with_current_cell():
|
||||
var cell_item = enhanced_gridmap.get_cell_item(Vector3i(current_position.x, 0, current_position.y))
|
||||
# Add custom interaction logic based on cell_item
|
||||
```
|
||||
|
||||
These examples demonstrate how you can build upon the provided player movement script to create more complex game mechanics that integrate seamlessly with the EnhancedGridMap plugin.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions to the EnhancedGridMap plugin are welcome! Please submit pull requests or issues on the project's GitHub repository.
|
||||
|
||||
## License
|
||||
|
||||
This plugin is released under the MIT License. See the LICENSE file for details.
|
||||
Reference in New Issue
Block a user