Merge branch 'release/2.1.5'

README.md

@@ -1,5 +1,5 @@
-# Welcome to Expresso Character Controller 👋
-![Version](https://img.shields.io/badge/version-2.1.4-blue.svg?cacheSeconds=2592000)
+# <img src="https://raw.githubusercontent.com/expressobits/character-controller/main/icon.png" alt= “icon” width="32" height="32"> Welcome to Expresso Character Controller 👋
+![Version](https://img.shields.io/badge/version-2.1.5-blue.svg?cacheSeconds=2592000)
 [![Documentation](https://img.shields.io/badge/documentation-yes-brightgreen.svg)](todo-doc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](MIT)
 
@@ -40,11 +40,14 @@ See in [Wiki](https://github.com/ExpressoBits/character-controller/wiki)
 ## Authors
 
 👤 **Rafael Correa**
+
 * Twitter: [@ScriptsEngineer](https://twitter.com/ScriptsEngineer)
 * Github: [@scriptsengineer](https://github.com/scriptsengineer)
 
 Based on the plugin https://github.com/Whimfoome/godot-FirstPersonStarter:
+
 👤 **Whimfoome**
+
 * Github: [@Whimfoome](https://github.com/Whimfoome)
 
 ## 🤝 Contributing

addons/character-controller/abilities/crouch_ability_3d.gd

@@ -1,19 +1,32 @@
 extends MovementAbility3D
-
 class_name CrouchAbility3D
 
+## Crouch Ability, change size collider and velocity of [CharacterController3D].
+
+## Speed multiplier when crouch is actived
 @export var speed_multiplier := 0.7
+
+## Collider that changes size when in crouch state
 @export var collision : CollisionShape3D
+
+## Raycast that checks if it is possible to exit the crouch state
 @export var head_check : RayCast3D
+
+## Collider height when crouch actived
 @export var height_in_crouch := 1.0
+
+## Collider height when crouch deactived
 @export var default_height := 2.0
-
+
+
+## Applies slow if crouch is enabled
 func get_speed_modifier() -> float:
 	if is_actived():
 		return speed_multiplier
 	else:
 		return super.get_speed_modifier()
-
+
+## Set collision height 
 func apply(velocity: Vector3, speed : float, is_on_floor : bool, direction : Vector3, delta: float) -> Vector3:
 	if is_actived():
 		collision.shape.height -= delta * 8

addons/character-controller/abilities/fly_ability_3d.gd

@@ -1,15 +1,19 @@
 extends MovementAbility3D
-
 class_name FlyAbility3D
 
+## Ability that gives free movement to [CharacterController 3D] completely ignoring gravity.
+
+## Speed modifier while this ability is active
 @export var speed_modifier := 2.0
-
+
+## Get actual speed modifier
 func get_speed_modifier() -> float:
 	if is_actived():
 		return speed_modifier
 	else:
 		return super.get_speed_modifier()
-
+
+## Apply velocity to [CharacterController3D]
 func apply(velocity: Vector3, speed : float, is_on_floor : bool, direction : Vector3, delta: float) -> Vector3:
 	if not is_actived():
 		return velocity

addons/character-controller/abilities/jump_ability_3d.gd

@@ -1,9 +1,13 @@
 extends MovementAbility3D
-
 class_name JumpAbility3D
 
+## Simple ability that adds a vertical impulse when actived (Jump)
+
+## Jump/Impulse height
 @export var height := 10
-
+
+
+## Change vertical velocity of [CharacterController3D]
 func apply(velocity : Vector3, speed : float, is_on_floor : bool, direction : Vector3, _delta : float) -> Vector3:
 	if is_actived():
 		velocity.y = height

addons/character-controller/abilities/sprint_ability_3d.gd

@@ -1,10 +1,13 @@
 extends MovementAbility3D
-
 class_name SprintAbility3D
 
-var _was_sprinting := false
+## Ability that adds extra speed when actived
+
+## Speed to be multiplied when active the ability
 @export var speed_multiplier := 1.6
-
+
+## Returns a speed modifier, 
+## useful for abilities that when active can change the overall speed of the [CharacterController3D], for example the [SprintAbility3D].
 func get_speed_modifier() -> float:
 	if is_actived():
 		return speed_multiplier

addons/character-controller/abilities/swim_ability_3d.gd

@@ -1,18 +1,41 @@
 extends MovementAbility3D
-
 class_name SwimAbility3D
 
+## swimming ability of [CharacterController3D].
+## 
+## There are three possible states: 
+## - Touching water
+## - floating in water
+## - Submerged
+##
+## Note: the [b]actived[/b] and [b]deactived[/b] signals are emitted when it is 
+## submerged(active) and surfaced(deactived)
+
+## Emitted when character controller touched water
 signal entered_the_water
+
+## Emitted when character controller stopped touching water
 signal exit_the_water
+
+## Emitted when we start to float in water
 signal started_floating
+
+## Emitted when we stop to float in water
 signal stopped_floating
 
+## Minimum height for [CharacterController3D] to be completely submerged in water.
 @export var submerged_height := 0.36
+
+## Minimum height for [CharacterController3D] to be float in water.
 @export var floating_height := 0.55
+
+## Speed multiplier when floating water
 @export var on_water_speed_multiplier := 0.75
+
+## Speed multiplier when submerged water
 @export var submerged_speed_multiplier := 0.5
-var raycast_path := NodePath("RayCast3D")
-@onready var raycast: RayCast3D = get_node(raycast_path)
+
+@onready var _raycast: RayCast3D = get_node(NodePath("RayCast3D"))
 
 var _is_on_water := false
 var _is_floating := false
@@ -29,10 +52,10 @@ func get_speed_modifier() -> float:
 		return super.get_speed_modifier()
 
 func set_active(a : bool) -> void:
-	_is_on_water = raycast.is_colliding()
+	_is_on_water = _raycast.is_colliding()
 
 	if _is_on_water:
-		_depth_on_water = -raycast.to_local(raycast.get_collision_point()).y
+		_depth_on_water = -_raycast.to_local(_raycast.get_collision_point()).y
 	else:
 		_depth_on_water = 2.1
 
@@ -55,7 +78,7 @@ func set_active(a : bool) -> void:
 func apply(velocity: Vector3, speed : float, is_on_floor : bool, direction : Vector3, delta: float) -> Vector3:
 	if not is_floating():
 		return velocity
-	var depth = get_floating_height() - get_depth_on_water()
+	var depth = floating_height - get_depth_on_water()
 	velocity = direction * speed
 #	if depth < 0.1: && !is_fly_mode():
 	if depth < 0.1:
@@ -64,22 +87,24 @@ func apply(velocity: Vector3, speed : float, is_on_floor : bool, direction : Vec
 	return velocity
 
 
+## Returns true if we are touching the water
 func is_on_water() -> bool:
 	return _is_on_water
 
 
+## Returns true if we are floating in water
 func is_floating() -> bool:
 	return _is_floating
 
 
+## Returns true if we are submerged in water
 func is_submerged() -> bool:
 	return is_actived()
 
 
-func get_floating_height() -> float:
-	return floating_height
-
-
+## Returns the height of the water in [Character Controller 3D].
+## 2.1 or more - Above water level
+## 2 - If it's touching our feet
+## 0 - If we just got submerged
 func get_depth_on_water() -> float:
 	return _depth_on_water
-

addons/character-controller/abilities/walk_ability_3d.gd

@@ -1,13 +1,21 @@
 extends MovementAbility3D
-
 class_name WalkAbility3D
 
+## Basic movement ability
+
+## Time for the character to reach full speed
 @export var acceleration := 8
+
+## Time for the character to stop walking
 @export var deceleration := 10
+
+## Sets control in the air
 @export_range(0.0, 1.0, 0.05) var air_control := 0.3
-
+
+
+## Takes direction of movement from input and turns it into horizontal velocity
 func apply(velocity: Vector3, speed : float, is_on_floor : bool, direction : Vector3, delta: float) -> Vector3:
-	if not active:
+	if not is_actived():
 		return velocity
 
 	# Using only the horizontal velocity, interpolate towards the input.