PathKit 2D – Pathfinding & AI toolkit for Godot 4.2+

PathKit 2D: pathfinding and AI toolkit for Godot 4.2+

Note: The demo visuals are rough placeholder art, not production quality; they only show what the features do. The toolkit works with square-grid 2D games: top-down (RPG, strategy/RTS, dungeon crawlers) and side-view platformers. Hex and isometric grids are not supported out of the box.

PathKit 2D is a 2D pathfinding toolkit written in pure GDScript. It covers grid A*, platformer jump graphs, flow-field crowds, formations and enemy movement AI. There is no GDExtension, no plugin to enable, no autoload and no class_name: copy the folder and preload() only the scripts you need. It includes 9 demo scenes, a 20-section tutorial and a full API reference.

Testing scope: tested on Linux with Godot 4.2.2, 4.3, 4.4.1, 4.5.2, 4.6.3 and 4.7.2. Tests ran headless on one reference VM, and the demo recordings were made on the Compatibility renderer (OpenGL 3). It has not been tested on Forward+, Mobile, real GPUs, web exports, Windows, macOS, mobile devices or Steam Deck. There is no web demo or free version, so please check the GIFs and docs list before buying.

Features

Core: grid pathfinding

• Grid (pk_grid.gd): walls and per-terrain move costs. Synchronous A* runs on Godot's C++ AStarGrid2D, and a time-sliced GDScript A* (start_query() / step()) can spread one search over several frames. Also includes per-unit terrain cost multipliers and path cost calculation.

  

• TileMap adapter: reads a TileMap (4.2) or TileMapLayer (4.3+) into the grid, using collision polygons and the optional custom data layers pk_solid, pk_terrain and pk_kind (solid / one-way / ladder).

  

• Multithreaded batch queries: one worker thread and one private AStarGrid2D copy each, with a synchronous run() or per-frame start() / poll(). On 4.2–4.4 it falls back to a single worker (see limitations).

  

• Debug drawing and debug view: grid, terrain tint and paths, plus an overlay for graph nodes and edges, jump arcs, flow-field arrows, heat maps and custom paths, with counts and stats text.

  

Top-down

• Movement layers: ground / air / water masks give walkers, swimmers, amphibians and flyers their own routes.

  

  

  

• Large units of any size: square footprint with no corner clipping. Terrain cost uses either the highest cost under the footprint or the anchor cell only.

  

• Click-target correction: snaps to the nearest reachable cell, and can plan a path that stops next to an object.
• Connected-region queries and exact line-of-sight segment checks.
• Path smoothing: string pulling plus corner pulling, with an optional clearance radius. It works for size-1 units and has fast and taut modes.

  

• Flyer grid from a platformer level (from_platform).
• Click-to-move node: move_to_world(), move_next_to() and an arrived signal.

  

• Replan queue: spreads path requests from many units over frames within a microsecond budget. Results arrive through the path_ready signal.

  

• NavigationServer2D adapter: builds a navigation map from the grid so you can compare against Godot's built-in navigation. This is for size-1 units only.

Platformer

• Jump graph: supports walk, fall, drop-through on one-way platforms, ladder climbing and jumps. Several jump abilities can share one graph and one build.

  

  

• Exact jump search with build(), which can also be split across frames with rebuild_all_async(). A faster but less complete build_fast() is also available.
• Runtime level edits: local edits with set_cell() and frame-split step().

  

• Doors with key tags and portals, which can chain. Path watching is available with watch_path.

  

• Bake, save and load with a checksum (save_bake() / load_bake()). prepare_dynamic() keeps loaded levels editable.

  

• Platform agent: a ready-made CharacterBody2D that follows the step list, with portal signals and hooks.
• Physics validator: checks every edge in physics at bake time. A failed jump is switched to its next possible arc or dropped. Edges created by local edits are checked too.
• Rebuild runner: runs local rebuilds at runtime within a time budget and checks new edges in physics on layers 31 and 32.
• Grid world helper: builds colliders for a cell grid and draws the level. The demos and tests use it.

Crowds

• Flow fields: one field per goal or goal set, shared by any number of agents. It can be computed at once or spread over frames, with optional hazard costs.

  

• Crowd: hundreds of circular agents on flow fields or point targets, with separation, sidestepping, wall sliding and doorway queuing.

  

• Formations: line, wedge and circle formations around a leader. A slot that lands in a wall moves to the nearest reachable cell.

  

AI (movement decisions only, no combat)

• Enemy AI for many agents: patrol (loop / ping-pong / random), chase, flee, keep distance and custom goals, with state_changed and waypoint_reached signals. Flee uses a safety field so agents avoid dead ends, and that field can update on a worker thread.

  

  

• Sight: exact grid line of sight, batch checks (visible_many), nearest-cover search and lists of hidden cells.

  

What's in the package (88 files)

• addons/pathkit2d/ (25 files): 23 scripts (ai 2, core 6, crowd 3, platformer 8, topdown 4), LICENSE.txt and THIRD_PARTY_NOTICES.txt.
• demo/scenes/ (19 files): a menu plus 8 self-playing demos, covering platformer, top-down, movement layers, a crowd of 100 / 500 / 1000 agents, formations, enemy AI, the debug view and an in-game benchmark table. Press Esc to return to the menu.
• demo/assets/ (9 files): Kenney CC0 art (pixel-platformer, tiny-dungeon, tiny-town), its licences and CREDITS.md. demo/shoot.gd is a screenshot helper.
• docs/ (11 files): README, GETTING_STARTED, 5 guides (top-down, platformer, crowds, AI, debug), API, DEMOS, PERFORMANCE and KNOWN_LIMITATIONS. docs/img/tutorial/ holds 18 tutorial pictures.
• Root (5 files): README.md, TUTORIAL.md, LICENSE.txt, THIRD_PARTY_NOTICES.txt and project.godot. The main scene is demo/scenes/00_menu.tscn.

The GIFs show purpose-built showcase scenes, so the demo scenes in the package look different.

Quick Start

• 1. Copy addons/pathkit2d into your project at res://addons/pathkit2d. There is no plugin to enable.
• 2. Open the project once so Godot imports the scripts.
• 3. preload() the scripts you need:

extends Node

const PKUnitGrid = preload("res://addons/pathkit2d/topdown/pk_unit_grid.gd")

func _ready() -> void:
    var grid = PKUnitGrid.new()
    grid.create(20, 12)
    for y in range(12):
        if y != 6:
            grid.set_solid(Vector2i(10, y), true)  # a wall with one gap
    var path: PackedVector2Array = grid.find_path_unit(Vector2i(1, 1), Vector2i(18, 10), PKUnitGrid.MOVE_GROUND, 1)
    var smooth: PackedVector2Array = grid.smooth_path(path, PKUnitGrid.MOVE_GROUND)
    print("raw ", path.size(), " smooth ", smooth.size())

Path points are cells, so add 0.5 to a point to get the cell centre. To see every demo, run demo/scenes/00_menu.tscn.

Tutorial and docs

TUTORIAL.md has one section per feature. Each section has a runnable snippet, a picture and a link to a demo or guide, and the snippets are checked automatically on Godot 4.2.2 and 4.7.2.

• 1. Install and preloads
• 2. Top-down paths and smoothing
• 3. Terrain costs
• 4. Walkers, swimmers and flyers (movement layers)
• 5. Large units
• 6. Click to move
• 7. Many units: the replan queue
• 8. Multithreaded batch queries
• 9. Reading a TileMap
• 10. Platformer paths
• 11. Different jump abilities
• 12. Changing the level at runtime
• 13. Doors, keys and portals
• 14. Bake, save and load
• 15. Flow-field crowds and avoidance
• 16. Formations
• 17. Enemy AI: patrol, chase, flee, keep distance
• 18. Sight and cover
• 19. Debug view
• 20. Going further

The package also includes GETTING_STARTED, the 5 guides, an API reference generated from the code's doc comments, PERFORMANCE, DEMOS and KNOWN_LIMITATIONS.

Testing scope and measured numbers

All tests ran headless on one reference Linux VM, using the Compatibility renderer only, on Godot 4.2.2, 4.3, 4.4.1, 4.5.2, 4.6.3 and 4.7.2. The addon does no rendering of its own apart from the optional debug nodes. Numbers are p95.

• 128×128 grid query: ≤ 2 ms on all 6 versions.
• 256×256 query with terrain costs: about 5.9 ms on 4.5–4.7 and 7.9–8.5 ms on 4.2–4.4.
• Platformer query on a 200×60 level: 0.51–0.66 ms.
• 500-agent crowd: arrives on all 3 test maps in 15.7–16.6 s.

Known limitations

The full list is in docs/KNOWN_LIMITATIONS.md. The slow spots are limited by GDScript speed.

• Taut smoothing takes 14.6–22.4 ms p95 on a 200-point path. taut = false is about 10× cheaper, and its paths are at most about 7% longer. Fast smoothing takes 0.33–0.38 ms p95 against a 0.3 ms target.
• Avoidance takes 1.26–2.22 ms for 100 agents and 4.86–5.86 ms for 500 agents. One agent can stall briefly in a doorway queue.
• build_fast() has a median of 309–335 ms on 4.2–4.4 and 217–264 ms on 4.5–4.7. It finds about 82% of the baked jumps, and about 36% of reachable start/goal pairs lose their path. We recommend baking, loading, then editing locally.
• Threaded batch queries give no speed-up on 4.2–4.4. Threaded AStarGrid2D is about 4× slower there, so calibrate() falls back to one worker. Threads help on 4.5+.
• Local rebuilds without the rebuild runner (or validate_rebuilds): about 96% of rebuilt edges walk correctly in physics, compared with 100% after a bake.
• Sight: visible_many() with 1000 checks takes 0.72–1.14 ms, or 1.1–1.6 ms under parallel load.
• Path smoothing and the NavigationServer2D adapter work for size-1 units only.

Requirements

• Godot 4.2 or newer (tested on 4.2.2–4.7.2). GDScript only, so there are no per-platform binaries.
• The demo project is set to the Compatibility renderer (gl_compatibility).

Licence and AI disclosure

Licence summary (the LICENSE.txt in the download is binding): one licence per purchaser, not transferable. You may use and modify PathKit 2D in unlimited personal and commercial games and apps, and ship it inside your exported game. You may not resell, re-upload or redistribute it or its source files, either on their own or in any asset pack, template or plugin, and you may not give copies to people who did not buy it. It is provided as is, without warranty.

Open-source games: these are fine, but your public repository must not contain the PathKit 2D source. Exclude addons/pathkit2d/ (for example via .gitignore) before publishing, and tell others to buy their own licence.

Demo art is by Kenney (CC0).

AI disclosure: AI assistance was used for the code, which Mothlight Studio reviewed. The demo art is by Kenney (CC0) and is not AI-generated.