godotengine / godotengine/godot-docs
CharacterBody2D documentation should include how to set position directly, i.e., how to "teleport"
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
v4.0.2.stable.official [7a0977ce2]
**Issue description:**
The CharacterBody2D documentation states "When moving a CharacterBody2D, you should not set its position property directly." But changing the position of a CharacterBody2D does not create any warnings or errors and seems to work in most cases. If it works fine, why do the docs say it shouldn't be done? The docs should explain this.
The extremely common use case for directly changing a CharacterBody2D's position is "teleporting" (i.e., moving to a new position without the need for any collision calculations), such as when resetting a player's position back to a spawn point after they have been killed. Googling how to teleport a KinematicBody2D (3.x precursor to CharacterBody2D) reveals many results with people asking about this. 4.x searches yield relatively few results for obvious reasons.
The CharacterBody2D documentation (and tutorial) should therefore be updated to expand on the statement "you should not set its position property directly". i.e., if it is indeed true, then it should explain why (the risks). It should also describe the best practice for teleporting given this is an extremely common use case.
**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/classes/class_characterbody2d.html
Also - the relevant tutorial:
https://docs.godotengine.org/en/stable/tutorials/physics/using_character_body_2d.html
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.