1

Description

"## Introduction\r\n\r\nThird person hero games display\/control usually consists in a camera orbiting the main protagonist (or player). The following script proposes to give the ability to use the two sticks of a joypad to move the said protagonist using the left stick and the camera using the right stick.\r\n\r\nWhen using the left stick, the player moves accordingly using the current camera position\/orientation as a reference.\r\n\r\nWhen using the right stick, the camera is moved around the vertical\/Y axis to orbit around the player. An additional parameter (using the Y axis of the right stick) can be used to set the camera distance\/elevation\/whatever you want.\r\n\r\nThe following script only manages the input and the transmission of the information using a signal. It's up to the signal receiver to manage the player position\/progression and camera placement (as there can be some subtleties like camera position smoothing\/obstacle avoidance and other player movement management that are out of this script scope).\r\n\r\n## Signal\r\n\r\nWhen at least one of the sticks is not resting position, the script will emit the signal `on_update` with the following parameters:\r\n* **subject_speed** : Speed ratio to be applied to the subject of the control (usually, the player). The ratio is already multiplied by the time delta (in seconds) with the last frame (see the `delta` parameter of `_process`)\r\n* **subject_angle** : Orientation of the subject along the Y axis, in radians. 0 means that the subject is oriented toward the positive Z axis.\r\n* **camera_y_angle** : Orientation of the camera around the Y axis.\r\n* **camera_parameter** : Additional camera parameter ranging from 0 to 1. Can be used for zoom in\/out or camera elevation\r\n\r\n> [!CAUTION]\r\n> The values are computed by taking frame timing delta into consideration. Those values can be used as-is without having to care about framerate adjustment. This also means that data received upon signal emission must be processed right away.\r\n\r\n## Parameters\r\n\r\nThe script can be tuned using the following parameters:\r\n* **dead_zone** _(default : 0.07)_ : The joypad sticks dead-zone value. This value is purely arbitrary and should be set after proper joypad calibration.\r\n* **camera_rotate_speed** _(default : PI)_ : Camera rotation speed in radians per second around the Y axis when the right stick is used on the X axis.\r\n* **camera_var_speed** _(default : 1.0)_ : Camera addition value variation speed when the right stick is used on the Y axis.\r\n\r\n## Usage\r\n\r\nHere is an simple example of this script usage. Given a scene with a plane as terrain, a capsule mesh as player and a camera, set a bare `Node` and attach the controller script to it.\r\n\r\n\r\n\r\nOn the main node, attach the following script:\r\n\r\n??? guide Example Script\r\n```gdscript\r\nextends Node3D\r\n\r\n@export var player : MeshInstance3D\r\n\r\n@export var camera : Camera3D\r\n\r\n@export var controller : TwoSticksThirdPersonController\r\n\r\n@export var player_speed : float = 1.\r\n\r\nfunc _ready() -> void:\r\n\tassert(player != null and camera != null and controller != null)\r\n\t\r\n\tvar mesh : Mesh = player.mesh\r\n\tif mesh is CapsuleMesh:\r\n\t\tplayer.position.y = (mesh as CapsuleMesh).height \/ 2.\r\n\t\r\n\tcontroller.on_update.connect(_adjust_camera)\r\n\t\r\n\t_adjust_camera(0., 0., 0., 0.)\r\n\r\nfunc _adjust_camera(move_speed : float, move_angle : float, camera_y_angle : float, camera_var : float) -> void :\r\n\tplayer.rotation.y = move_angle\r\n\tplayer.translate(Vector3(0, 0, move_speed * player_speed))\r\n\r\n\tvar cam_pos : Vector3 = player.position + Vector3.BACK.rotated(Vector3.LEFT, camera_var).rotated(Vector3.DOWN, camera_y_angle) * 8.\r\n\tcamera.look_at_from_position(cam_pos, player.position)\r\n```\r\n???\r\n\r\n> [!WARNING]\r\n> Don't forget to set the parameters so the script can link to all the needed nodes (camera, player model, twin stick controller)"

Main code

class_name TwoSticksThirdPersonController
extends Node

signal on_update(subject_speed : float, subject_angle : float, camera_y_angle : float, camera_parameter : float)

@export var dead_zone : float = 0.07

@export var camera_rotate_speed : float = PI

@export var camera_var_speed : float = 1.

@onready var left_stick : Vector2 = Vector2(0., 0.)

@onready var right_stick : Vector2 = Vector2(0., 0.)

@onready var update_direction : bool = false

@onready var update_camera : bool = false

@onready var y_angle : float = 0.

@onready var other_value : float = 0.

@onready var move_angle : float = 0.

func _input(event : InputEvent) -> void:
	if event is InputEventJoypadMotion:
		var jev : InputEventJoypadMotion = event
		var value : float = jev.axis_value if abs(jev.axis_value) > dead_zone else 0.

		match jev.axis:
			JOY_AXIS_LEFT_X:
				left_stick.x = value
			JOY_AXIS_LEFT_Y:
				left_stick.y = value
			JOY_AXIS_RIGHT_X:
				right_stick.x = value
			JOY_AXIS_RIGHT_Y:
				right_stick.y = value
			_:
				pass

		update_direction = not (is_zero_approx(left_stick.x) and is_zero_approx(left_stick.y))
		update_camera = not (is_zero_approx(right_stick.x) and is_zero_approx(right_stick.y))

func _process(delta : float) -> void:
	if update_direction or update_camera:
		y_angle += right_stick.x * camera_rotate_speed * delta
		if y_angle < 0:
			y_angle = 2 * PI + y_angle
		elif y_angle > 2 * PI:
			y_angle -= 2 * PI
		other_value = clampf(
			other_value - right_stick.y * camera_var_speed * delta,
			0., 1.)
		var transformed_left : Vector2 = left_stick.rotated(y_angle)
		var move_speed : float = transformed_left.length()
		if not is_zero_approx(move_speed):
			move_angle = atan2(transformed_left.x, transformed_left.y)
		
		on_update.emit(move_speed * delta, move_angle, y_angle, other_value)

Comments