Merge pull request #9 from GDquest/features/project-asset

Project Asset

Author: NathanLovato

Game.tscn

@@ -1,7 +1,6 @@
-[gd_scene load_steps=11 format=2]
+[gd_scene load_steps=10 format=2]
 
-[ext_resource path="res://src/Camera/Camera.tscn" type="PackedScene" id=1]
-[ext_resource path="res://src/Player/Player.tscn" type="PackedScene" id=2]
+[ext_resource path="res://src/Player/Player.tscn" type="PackedScene" id=1]
 
 [sub_resource type="SpatialMaterial" id=1]
 albedo_color = Color( 1, 0.537255, 0.8, 1 )
@@ -37,6 +36,7 @@ mesh = SubResource( 2 )
 material/0 = null
 
 [node name="StaticBody" type="StaticBody" parent="TestMap/Ground"]
+editor/display_folded = true
 
 [node name="CollisionShape" type="CollisionShape" parent="TestMap/Ground/StaticBody"]
 shape = SubResource( 3 )
@@ -169,7 +169,4 @@ shape = SubResource( 8 )
 transform = Transform( 0.766044, 0.166366, -0.620885, 0.271654, 0.791635, 0.547283, 0.582563, -0.587909, 0.561234, 0, 12, 0 )
 shadow_enabled = true
 
-[node name="Camera" parent="." instance=ExtResource( 1 )]
-transform = Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1.75, 0 )
-
-[node name="Player" parent="." instance=ExtResource( 2 )]
+[node name="Player" parent="." instance=ExtResource( 1 )]

README.md

@@ -1,17 +1,72 @@
-# Godot 3d Mannequin
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [Quick Start Guide](#quick-start-guide)
+    - [Controls](#controls)
+- [How it works](#how-it-works)
+    - [Player](#player)
+    - [Camera](#camera)
+- [Configuration](#configuration)
+- [Customization](#customization)
+- [Credits](#credits)
+- [Support our work](#support-our-work)
+
+<!-- markdown-toc end -->
 
 An Open Source 3d character and character controller for the Godot game engine.
 
 ![The mannequin in-game](./assets/screenshots/prototype-1.png)
 
 This is a third person character controller designed to work both with the keyboard and a gamepad. It features a camera that can auto-rotate or that can be controlled with a joystick.
 
-## Credits
+# Quick Start Guide #
+
+The 3D Third Person Character Controller is made of two scenes:
+
+* `Camera.tscn` - A 3D camera rig with a state machine for aiming
+* `Player.tscn` - A `KinematicBody` with a state machine for player movement. Contains an instance of `Camera`. It also includes the animated 3D mannequin.
+
+To use the default character, instance `Player` in your game. See `Game.tscn` for an example. In this demo, the obstacles are mesh instances with static body collisions making up a cube world.
+
+## Controls ##
+
+The game supports both mouse and keyboard, and the gamepad.
+
+# How it works #
+
+## Player ##
+
+The scene that deals with the movement, collision, and logic of the player. The player is a KinematicBody with a capsule collision shape, and the movement logic is within a [Finite State Machine](http://gameprogrammingpatterns.com/state.html).
+
+The scene also holds an instance of the `PlayerMesh` for animation purposes. This scene lives in the `PlayerMesh.tscn` scene. It holds the skeletal rig for the mesh's animation, the 3D model of the body and head sepearately, and the animation tree and player to control the animation workflow of the model. The lot is wrapped up in a spatial node with some logic to transition to which animation based on which state the player is in.
+
+## Camera ##
+
+The scene that deals with the Camera movement. It follows the Player in the game, but in code it moves and rotates separately from it. It has a `SpringArm` node to help with preventing collision with level geometry - moving the viewpoint forwards to prevent moving the camera inside geometry. It also has a system that holds the raycast for aiming-mode, and the 3D sprite that is a projected reticule. The logic is held in a finite state machine.
+
+# Configuration #
+
+To change the player and the camera's behavior, you need to change properties on the corresponding states in their state machine.
+
+Most of the configuration available for player movement are located on the `Move` state in the Player scene - the player speed and the rotational speed.
+
+The Camera has more options. On the main Camera state in the Camera scene are items like the default field of view, whether Y is inverted, and sensitivity.
+
+In addition, the Aim state allows some finer-tuned changes, like whether the aiming camera is first or third person, and by how much it should be offset over-the-shoulder of the character.
+
+# Customization #
+
+While the scenes can be modified extensively with new nodes and raw code, the state machine model allow for some simple, new functionality with relative ease.
+
+As an example, there is the `Extensions` folder which contains additional player states for using the aiming view to fire a hookshot that pulls you towards the reticle. Once those states have been added to the Player's `Move` state, you only need to replace the return statement in Move's `enter` with code like `owner.camera.connect("aim_fired", self, "on_Camera_aim_fired")` and Move's `exit` with code like `owner.camera.disconnect("aim_fired", self, "on_Camera_aim_fired")`
+
+# Credits #
 
 1. The Godot mannequin is a character made by [Luciano Muñoz](https://twitter.com/lucianomunoz_) In blender 2.80.
 1. Godot code by Josh aka [Cheeseness](https://twitter.com/ValiantCheese)
+1. Additional code by Francois Belair aka [Razoric480](https://twitter.com/Razoric480)
 
-## Support our work
+# Support our work #
 
 This free series is sponsored by our [platformer game creation course](https://gdquest.mavenseed.com).
 

icon.png

@@ -1,14 +1,24 @@
+tool
 extends Spatial
+"""
+Simple accessor class to let the nodes in the Camera scene access the player
+or some frequently used nodes in the scene itself caching the call to get_node
+"""
 
 
 signal aim_fired(target_vector)
 
 onready var camera_state: State = $StateMachine/Camera
 onready var aim_ray: RayCast = get_node("AimRay")
 
-var player: Player
+var player: KinematicBody
 
 
 func _ready() -> void:
-	player = get_tree().root.find_node("Player", true, false)
-	assert(player)
+	set_as_toplevel(true)
+	yield(owner, "ready")
+	player = owner
+
+
+func _get_configuration_warning() -> String:
+	return "Missing player node" if not player else ""

src/Camera/Camera.gd

@@ -10,11 +10,13 @@
 [node name="Camera" type="Spatial"]
 script = ExtResource( 1 )
 
-[node name="Camera" type="Camera" parent="."]
-transform = Transform( 1, 0, 0, 0, 0.866025, 0.5, 0, -0.5, 0.866025, 0, 3, 5 )
-current = true
+[node name="SpringArm" type="SpringArm" parent="."]
+transform = Transform( 1, 0, 0, 0, 0.87462, 0.48481, 0, -0.48481, 0.87462, 0, 0.5, 0.5 )
+spring_length = 5.0
+margin = 0.5
 
-[node name="OcclusionRay" type="RayCast" parent="."]
+[node name="Camera" type="Camera" parent="SpringArm"]
+current = true
 
 [node name="AimRay" type="RayCast" parent="."]
 transform = Transform( 1, 0, 0, 0, 0.866025, 0.5, 0, -0.5, 0.866025, 0, 0, 0 )

src/Camera/Camera.tscn

@@ -1,4 +1,8 @@
 extends State
+"""
+Logic state for the camera where configuration are made to the camera to set
+the field of view, position offset (over the shoulder), etc.
+"""
 
 
 export var first_person_aiming: bool = false

src/Camera/CameraStates/Aim.gd

@@ -1,11 +1,19 @@
 extends State
+"""
+Parent state for all camera based states for the Camera. Handles input based on
+mouse/gamepad and movement and configuration based on which state we're using.
 
+This state holds all of the main logic, with the state itself being configured
+or have its functions overriden or called by the child states. This keeps the
+logic contained in a central location while being easily modifiable.
+"""
 
-onready var camera: Camera = owner.get_node("Camera")
+
+onready var camera: SpringArm = owner.get_node("SpringArm")
+onready var camera_view: Camera = camera.get_node("Camera")
 onready var initial_position: = camera.translation
 onready var initial_anchor_position: Vector3 = owner.translation
 
-onready var occlusion_ray: RayCast = owner.get_node("OcclusionRay")
 onready var aim_target: Sprite3D = owner.get_node("AimTarget")
 
 export var default_fov: = 70.0
@@ -22,7 +30,6 @@ var _is_aiming: = false
 
 
 func _ready():
-	occlusion_ray.set_cast_to(initial_position)
 	Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)
 
 
@@ -58,18 +65,10 @@ func physics_process(delta: float) -> void:
 	elif owner.rotation.y < -PI:
 		owner.rotation.y += 2 * PI
 
-	if camera.fov != _current_fov:
-		camera.fov = lerp(camera.fov, _current_fov, 0.05)
+	if camera_view.fov != _current_fov:
+		camera_view.fov = lerp(camera_view.fov, _current_fov, 0.05)
 
-	# If there is a body between the camera and the player, move the camera closer
-	occlusion_ray.force_raycast_update()
-	if occlusion_ray.is_colliding():
-		var global_offset = camera.global_transform
-		if global_offset.origin != occlusion_ray.get_collision_point() + _offset:
-			global_offset.origin = occlusion_ray.get_collision_point() + _offset
-			camera.global_transform = global_offset
-	elif camera.translation != initial_position + _offset:
-		camera.translation = lerp(camera.translation, initial_position + _offset, 0.05)
+	camera.translation = lerp(camera.translation, initial_position + _offset, 0.05)
 
 
 func enter(msg: Dictionary = {}) ->void:
@@ -142,4 +141,4 @@ static func get_move_direction() -> Vector3:
 			Input.get_action_strength("move_right") - Input.get_action_strength("move_left"),
 			0,
 			Input.get_action_strength("move_back") - Input.get_action_strength("move_front")
-		)
+		)

src/Camera/CameraStates/Camera.gd

@@ -1,4 +1,7 @@
 extends State
+"""
+Logic state for the camera - implies no modification to the camera settings.
+"""
 
 
 func unhandled_input(event: InputEvent) -> void:

src/Camera/CameraStates/CameraDefault.gd

@@ -1,4 +1,7 @@
 extends State
+"""
+State that does not involve gravity or further movement until released.
+"""
 
 
 func unhandled_input(event: InputEvent) -> void:

src/Player/MoveStates/Hang.gd renamed to src/Extensions/PlayerStates/Hang.gd

@@ -1,4 +1,9 @@
 extends State
+"""
+Hookshot style state for the player - gets a destination from an outside
+piece of logic (in this case, the Camera's aim state firing with a raycast)
+and flies through the air to reach it.
+"""
 
 
 var zip_speed:= 10.0

src/Player/MoveStates/Zip.gd renamed to src/Extensions/PlayerStates/Zip.gd

@@ -1,16 +1,17 @@
 extends State
+"""
+State for when the player is jumping and falling.
+"""
 
 
 func physics_process(delta: float) -> void:
-	#TODO: Adjust peak of jump height depending on when jump input is released
 	_parent.velocity -= Vector3(0, delta * _parent.max_speed.y, 0)
 	_parent.physics_process(delta)
 
 	if owner.is_on_floor():
 		_state_machine.transition_to("Move/Idle")
 	if owner.is_on_ceiling():
 		_parent.velocity.y = 0
-	#if at ledge, transition to ledge
 
 
 func enter(msg: Dictionary = {}) -> void:
@@ -19,4 +20,4 @@ func enter(msg: Dictionary = {}) -> void:
 
 
 func exit() -> void:
-	_parent.exit()
+	_parent.exit()

src/Player/MoveStates/Air.gd

@@ -1,4 +1,8 @@
 extends State
+"""
+State for when there is no movement input.
+Supports triggering jump after the player started to fall.
+"""
 
 
 onready var jump_delay: Timer = $JumpDelay
@@ -29,4 +33,4 @@ func enter(msg: Dictionary = {}) -> void:
 
 
 func exit() -> void:
-	_parent.exit()
+	_parent.exit()

src/Player/MoveStates/Idle.gd

@@ -1,4 +1,11 @@
 extends State
+"""
+Parent state for all movement-related states for the Player.
+
+Holds all of the base movement logic. 
+Child states can override this state's functions or change its properties. 
+This keeps the logic grouped in one location.
+"""
 
 
 export var max_speed: = Vector3(50.0, 50.0, 500.0)
@@ -17,32 +24,36 @@ func unhandled_input(event: InputEvent) -> void:
 func physics_process(delta: float) -> void:
 	var input_direction: = get_input_direction()
 
-	#The basis holds the (right, up, and -forwards) vectors of our camera.
-	#Multiplied by our input and summed together gets us a final direction vector relative to the camera
+	# Calculate a move direction vector relative to the camera
+	# The basis stores the (right, up, -forwards) vectors of our camera.
 	var forwards: Vector3 = owner.camera.global_transform.basis.z * input_direction.z
 	var right: Vector3 = owner.camera.global_transform.basis.x * input_direction.x
 	var move_direction: = (forwards + right).normalized()
 	move_direction.y = 0
 
-	#Rotation
-	owner.look_at(owner.global_transform.origin + move_direction, Vector3.UP)
+	# Rotation
+	if move_direction:
+		owner.look_at(owner.global_transform.origin + move_direction, Vector3.UP)
 
-	#Movement
+	# Movement
 	var new_velocity = calculate_velocity(velocity, max_speed, move_speed, delta, move_direction)
 	if new_velocity.y == 0:
 		new_velocity.y = -0.01
 	owner.move_and_slide(new_velocity, Vector3.UP)
 
 
 func enter(msg: Dictionary = {}) -> void:
-	owner.camera.connect("aim_fired", self, "on_Camera_aim_fired")
+	return
 
 
 func exit() -> void:
-	owner.camera.disconnect("aim_fired", self, "on_Camera_aim_fired")
+	return
 
 
-func on_Camera_aim_fired(target_vector: Vector3) -> void:
+"""Callback to transition to the optional Zip state
+It only works if the Zip state node exists.
+It is intended to work via signals"""
+func _on_Camera_aim_fired(target_vector: Vector3) -> void:
 	_state_machine.transition_to("Move/Zip", { zip_target = target_vector })
 
 

src/Player/MoveStates/Move.gd

@@ -1,4 +1,7 @@
 extends State
+"""
+Basic state when the player is moving around until jumping or lack of input.
+"""
 
 
 func unhandled_input(event: InputEvent) -> void:
@@ -18,4 +21,4 @@ func enter(msg: = {}) -> void:
 
 
 func exit() -> void:
-	_parent.exit()
+	_parent.exit()

src/Player/MoveStates/Run.gd

@@ -1,10 +1,14 @@
+tool
 extends KinematicBody
 class_name Player
+"""
+Helper class for the Player scene's scripts to be able to have access to the
+camera and its orientation.
+"""
 
 
-var camera: Camera
+onready var camera: Spatial = $Camera
 
 
-func _ready() -> void:
-	camera = get_tree().root.find_node("Camera", true, false)
-	assert(camera)
+func _get_configuration_warning() -> String:
+	return "Missing camera node" if not camera else ""