Fixing CharacterBody2D Snagging on TileMap Corners in Godot 4

The Problem: The "Invisible Wall" Effect

When moving a CharacterBody2D across a TileMap, the character may intermittently jerk, slow down, or stop completely while traversing a flat floor or a smooth interior corner. This happens even when there are no visible obstacles and the input is continuous. This is typically caused by the physics engine detecting a collision with the internal edge (the seam) between two adjacent collision shapes in the TileMap, treating a flat surface as a series of small walls.

Diagnostic Matrix

Symptom	Likely Cause	Physics Behavior
Stuttering on flat ground	Edge-to-edge seam conflict	Collision resolution pushes the body backward
Getting stuck in inside corners	Simultaneous multi-tile contact	Conflicting normal vectors halt movement
Consistent blocking at specific tiles	Incorrect collision shape definition	Actual collision geometry overlap

Step-by-Step Troubleshooting

1. Enable Collision Debugging:

   Go to Debug > Visible Collision Shapes in the top menu and run the scene. Observe the character's shape as it hits a seam. If you see the shape "bounce" or jitter slightly at the junction of two tiles, you are dealing with a seam conflict.

2. Inspect Collision Geometry:

   Check the TileSet editor. If every tile has an individual rectangular collision shape, the physics engine must resolve collisions for each rectangle separately. This is the primary source of snagging.

3. Verify Collision Margins:

   Check the CollisionShape2D assigned to your CharacterBody2D. If the shape is a perfect rectangle matching the tile size, it is more prone to snagging than a capsule or a slightly rounded shape.

Targeted Fixes

Option A: Use TileMap Terrains (Recommended)

Instead of per-tile collision boxes, use the Terrain system to create merged collision shapes. This removes the internal seams entirely.

• In the TileSet panel, navigate to Terrains.
• Define a Terrain Set and assign the relevant tiles to a Terrain.
• Ensure the collision is set to follow the terrain boundaries rather than individual tile boxes. This merges adjacent collision shapes into a single continuous polygon.

Option B: Modify the Collision Shape

If you cannot use terrains, changing the geometry of the player's collision shape can reduce the frequency of snags.

• Replace Rectangles with Capsules: A CapsuleShape2D allows the character to "slide" over small seams that would otherwise catch a sharp 90-degree corner.
• Adjust the Safe Margin: In the CharacterBody2D inspector, locate the Safe Margin property. A very small margin can sometimes cause the body to get stuck; increasing it slightly (e.g., to 0.08 or 0.1) can help the engine resolve collisions more smoothly.

Option C: Adjust Movement Logic

If using move_and_slide(), ensure your floor max angle is configured correctly to prevent the character from treating a slight seam as a wall.

# Example: Ensuring movement remains fluid
# Run this in your CharacterBody2D script

func _physics_process(delta):
    var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    velocity = input_dir * speed
    
    # move_and_slide() handles the sliding logic automatically
    # Ensure 'floor_max_angle' in the inspector is set to a reasonable value (e.g., 45 degrees)
    move_and_slide()

Verification and Risks

Verification: Run the scene with Visible Collision Shapes enabled. Move the character in a straight line across at least five tile seams. The motion should be constant, and the character's velocity vector should not drop to zero unless a legitimate wall is hit.

Risks:

• Clipping: Increasing the Safe Margin too much may cause the character to appear to float slightly away from walls.
• Collision Leaks: Merging shapes via Terrains can occasionally create gaps if tiles are not aligned perfectly; always verify that the player cannot pass through intended walls.

Escalation Criteria

If the character still snags after implementing merged terrain collisions and using a CapsuleShape2D, the issue may be related to the physics engine's precision at specific scales. At this point:

• Check if your project scale is extremely small (e.g., 1 pixel = 1 unit), which can cause floating-point errors.
• Consider implementing a RayCast2D based movement system to manually detect walls and ignore seams.
• Create a minimal reproduction project (one player, one TileMap) to determine if the behavior persists across different Godot 4.x versions.