gdquest-demos / godot-3d-mannequin

An Open Source 3d character and character controller for the Godot game engine

Open 3D Mannequin is an Open Source 3d character and character controller for the Godot game engine

⚠ The project only supports Godot version 3.2 and above.

➡ Follow us on Twitter and YouTube for free game creation tutorials, tips, and news! Get one of our Godot game creation courses to support our work on Free Software.

Table of Contents

• Quick Start Guide
  • Controls
• How it works
  • Player
  • CameraRig
• Configuration
• Customization
• Credits
• Support our work

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.

Quick Start Guide

The 3D Third Person Character Controller is made of two scenes:

• CameraRig.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 CameraRig. 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.

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.

CameraRig

The scene that deals with the CameraRig 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 CameraRig has more options. On the main CameraRig state in the CameraRig 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")

Animating the character

The source Blender file is available in the releases tab. The character comes with all its animations. At first glance, it can look like it is lacking a rig.

Instead of a complex rig with many controls, we use ephemeral rigs as seen in Richard Lico's 2018 GDC talk Animating Quill. To do so, we work with the Blender add-on Rig on the Fly. This allows you to quickly generate a rig and controls adapted to the animation at hand. Once the animation is done, you bake it, and you're done!

Credits

1. The Godot mannequin is a character made by Luciano Muñoz In blender 2.80.
2. Godot code by Josh aka Cheeseness
3. Additional code by Francois Belair aka Razoric480

Support our work

GDQuest is a social company focused on education and bringing people together around Free Software.

This Free Software is sponsored by our course Code a Professional 3D Character with Godot.

We share the techniques professionals use to make games and open source the code for most of our projects on our GitHub page.

You can:

• Join the community on Discord
• Follow us on Twitter

Licenses

This project is dual-licensed:

• The source code is available under the MIT license.
• Art assets (images, audio files) are CC-By 4.0. You can attribute them to GDQuest and contributors (https://www.gdquest.com/).

godot-3d-mannequin's Issues

Open source is an ultra stupid mindset, promoted by worthless clowns

@NathanLovato This post is in response to the certain silly and worthless guys at GDquest, and some of its slave worthless members (including razvan)
Shame on them, cheap slaves. Shame on them cheap loser slaves for promoting dumpsters in socities called "universities" [dumpsterversities]. Shame on razvan for boasting about his stupidity. How extremely dumb and childish you are for promoting those ultra racist clowns. GDquest and godot and open-source have no potential and are a complete failure. Death to "univeristies". Death to every low life lower clown who uses those stupid and childish and pathetic "prefixes" when mentioning first name. Death to open source. Death to GDQuest. Death to godot. Hope you clown devs have a tragic life and painful death.
And another thing....
Stop making lies about real Engineering. Engineering has nothing to do with sitting behind a keyboard and writing code or games. Engineering is a real subject. Engineering means designing and building real mechanical systems, like vehicular engines and turbojets. Sound and software devs are the biggest liars. Game/software devs have absolutely nothing to do with engineering, they are just being stupid wannabe liars. They will never be engineers, not even close. In fact, they don't even know what it takes to be an engineer. None of you are engineers, and you'll never even be close. So stop being disrespectful to real engineers (mechanical engineering is real engineering, and nothing else)
Mechanical Engineering is the ONLY ENGINEERING. Period.

Character movement

I don't have precise requirements for the character's movement yet as we need a prototype first. We can do some back-and-forth to get the feel right.

The character should support platform and action. I'd use Zelda games as a reference:

• BotW: https://www.youtube.com/watch?v=r2JtSXXY_WY (same video as in #3 )
• The Wind Waker: https://youtu.be/2xnA9tAqaUg?t=727

Technical constraints

The character should use root motion for ground movement.

The character sometimes falls when walking over the gridmap

Sometimes, when moving over the cubes in the gridmap, Godot treats the character as if it was falling for a split second. This happens where colliders are touching one another.

Use animation name suffixes to add support for looping animations

iFire patched the Godot engine today to fix animation loops that are not working on inherited scenes from gltf.

Now we can add the cycle or loop keywords at the start or at the end of the animation names to make them import as looping animations.

Doing this will make it much easier to reimport and update the character.

CAMERA: Camera y inversion can't be toggled by pressing the intended input during gameplay

I'm submitting a...

• Bug report.
• Feature request.

Bug report

What is the current behavior?
Camera y rotation stays the same after pressing the intended input (default input = Control+Y).

What is the expected behavior?
Camera y rotation become inverted after pressing the intended input (default input = Control+Y).

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.

1. Click Play button or (F5)
2. Observe the camera y roation as the user move the mouse back and forth
3. Try to enable the camera y inversion with [Control+Y]
4. Observe the camera y roation again as the user move the mouse back and forth

Other

Other information
This issue was found on release v0.3.0
The camera y inversion action (toggle_y_inversion) from the input map settings does not seems to be called in any function. For a temporary fix, I added those following lines of code in the Camera.gd script under unhandled_input(event):

if event.is_action_pressed("toggle_y_inversion") and is_y_inverted == false:
	is_y_inverted = true
elif event.is_action_pressed("toggle_y_inversion") and is_y_inverted == true:
	is_y_inverted = false

Make Mannequiny look at the target in the aim state

When aiming, the character's face doesn't turn towards the place the player is aiming. It'd look and feel more immersive if Mannequiny would turn its head, and maybe its chest a bit, up to a maximum angle:

3rd-person camera

The Mannequin should support 3rd person gameplay, especially platform and action games to start with.

I've looked at different games, and for these, the character tends to be centered in the middle of the screen horizontally (unlike a shooter where the camera can be on one of the character's sides):

• Zelda BotW: https://www.youtube.com/watch?v=r2JtSXXY_WY
• Mario Galaxy 2: https://youtu.be/x2dR5dfiqng?t=1297
• Dark Souls 3: https://youtu.be/CPhoprLb7kM?t=731

It should support playing with a gamepad and joysticks, as well as keyboard and mouse.

Update the screenshots

Use nicer screenshots in the readme and on the asset library: https://godotengine.org/asset-library/asset/440

Workaround For Collisions

Currently the collisions work poorly visually. The head and parts of characters body are getting inside the wall.

I don't know if this is within the scope of the example but do you plan to address it?

Can't open the project

Hi,
I downloaded the project and imported it in Godot v3.2.1.

There seems to be something wrong with the dependencies in Mannequiny.tscn.
I can't open or run the project at all on windows.

CameraRig.tscn changes unexpectedly in filesystem based on property updates

I'm submitting a...

• [ x] Bug report.
• Feature request.

Bug report

What is the current behavior?

src/Player/Camera/CameraRig.tscn
thrashes on the filesystem

-length_range = Vector2( 3, 6 )
-zoom = 0.5

then it will be added to the tscn file after using the editor, running the game again.

What is the expected behavior?

It's unexpected that the tscn would change just based on using the editor and running the game without editor changes.

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.

Using git underneath the project reveals this quickly.

My assumption is that this is an issue with using "tool" in the SpringArm.gd source file?

Towards more open source prototype assets

I think the 3D mannequin is a super nice idea!
This morning I saw this package on Humble bundle:
https://youtu.be/KAiun66iyBA

And I thought, hey, why not doing a open source bundle of prototype assets? :D Looking at the number of assets in the pack above, it could be a community effort, and we might need to get some organisation around it. But I think it could be a thing!

The 3D mannequin is a step towards this and so I thought it would be nice to contact you, to see what you think about it.

Add root motion support

The character's rig supports root motion, but the animations were not designed for it.

Use the c_traj bone in the rig to animate the root motion in the Blender file.

You can find the blend file in the latest release.

Prepare for release on the asset library

To do after/along with #6

This open mannequin is a free project for the community. The goal is to have it on the Godot asset library so people can download it and get started prototyping their games.

Tasks

• Write a getting started guide
• Adapt the code and project so it's easy to reuse in a new Godot game
• Create the first GitHub release, with a copy of the .blend file attached, so people can use and contribute animations

Animations blending

Hi,

About the animations they look very rough and cluncky without blending.

You can change the blending on the character AnimationTree, click on the connecting arrows and change their "Xfade time" property to 0.3, then animations will look way more better.

BTW it's great, it should become a starter template for Godot on project creation for fast prototyping.

Make the rig easier to export for everyone

Problem: Mannequiny was rigged via a Blender add-on, auto-rig pro.

This saved us a lot of time, the tool is great, but it has one limitation: you need the add-on, or at least the export code from the add-on to export an optimized version of the character for games.

We would like to find a way to make it easier for everyone to use the rig and export for games, without losing the animations.

How should we go about that? Is it necessary to redo the rig? Would it be possible to keep the current rig, separating the armature we need to export to the game engine from the control bones?

We would appreciate the insights of a professional game animator / rigger in the matter. What would be the best approach?

You can download the .blend file with the animated character here: https://github.com/GDQuest/godot-3d-mannequin/releases/tag/v0.3.0

Camera not returning to correct position after leaving the aim state

When entering the aim state and then leaving it again the camera is not returned into its old position but ends up slightly higher. This is far more obvious if the length of the SpringArm is reduced.

This could also be a problem with the nightly build I'm using but as the project won't open with the latest stable build I'm not able to test that.

Add jump and fall animations

The jump animation currently looks awkward. The character should use slices of the jump animation from the blend file to have nicer jump and fall motion.

Re-rig the mannequin to export game-friendly animation

We're having trouble with export with Rigify, it'd take some code to make the rig game-friendly on export.

I've started using autorig pro to re-rig and retarget the original character animation, taking the character from 150+ joints to 44.

Memory leakage in project, even in editor

• Bug report.
• Feature request.

Bug report

When I open project(even in editor) and close it, then I see leak:

ERROR: ~List: Condition "_first != __null" is true.
   At: ./core/self_list.h:112.
ERROR: ~List: Condition "_first != __null" is true.
   At: ./core/self_list.h:112.
WARNING: cleanup: ObjectDB Instances still exist!
   At: core/object.cpp:2071.
ERROR: clear: Resources Still in use at Exit!
   At: core/resource.cpp:476.

When I add -v argument to Godot run command, then I see that res://src/Main/StateMachine/State.gd leaks

Orphan StringName: msg
Orphan StringName: owner
Orphan StringName: unhandled_input
Orphan StringName: GDScriptNativeClass
Orphan StringName: is_in_group
Orphan StringName: node
Orphan StringName: res://src/Main/StateMachine/State.gd
Orphan StringName: enter
Orphan StringName: _parent
Orphan StringName: _state_machine
Orphan StringName: _get_state_machine
Orphan StringName: get_parent
Orphan StringName: Node
Orphan StringName: InputEvent
Orphan StringName: event
Orphan StringName: physics_process
Orphan StringName: _init
Orphan StringName: _ready
Orphan StringName: exit
Orphan StringName: GDScript
Orphan StringName: delta
Orphan StringName: process

I'm not sure what cause leaks, but probably returning inside class, objects of this class or parent class.

Fill hole in the white slice near the character's hips

The mannequin has a hole in the mesh that shows during various animations.

Add interpolation to the facing direction when moving

I'm submitting a...

• Bug report.
• Feature request.

Feature request

Add interpolation to the player's angle instead of immediately snapping to the move direction

I think the character controller is much more appealing when a bit of interpolation is added to the angle changing as the character moves around. Especially when using digital controls like a keyboard or dpad, the robotic looking snap as the character turns looks jarring.

I gave it a shot myself and recorded a quick video

This was where I added the interpolation

Slope Support

The character continues movement while no input is given on sloped terrain. A ray cast downward to detect if distance to ground <= floor value + no input {halt movement} , should fix this issue. I have tried this in the script but its a bit buggy. Are there plans to implement sloped terrain support soon? Perhaps, I could make a pull request with the current code I have though this should be a very simple fix at core level.

Review and possibly simplify the code

Josh worked on this character directly, I just briefly looked at the code, so it could use a second pair of eyes. Go through the character's code and look for places where it can be simplified or refined.

Josh suggested to replace rotation logic with quaternions, which would shorten the code and prevent issues like gimbal lock or the need to unwind in some case. He went with rotation in degrees as this will end up in a tutorial, because quaternions are harder to understand compared to angles.

But as quaternions solve some problems that can be tricky when you use angles and can easily produce smooth, graceful rotations, we should consider using them.

Tasks

• Review the code and simplify if possible
• Document the main scripts with a docstring at the top
• Figure out if we should use quaternions (you can create a new task for that)

Mannequin does not show up in the Editor built-in AssetLib browser

I'm submitting a...

• [x ] Bug report?
• [ x] Feature request?

Bug report

What is the current behavior?
Despite it being available in the Asset Library, it's not available in the Godot AssetLib browser in Godot 3.5.1 or earlier.

Search prompts I have tried: "Mannequin", "Mannequiny", "GDQuest"

What is the expected behavior?
Have it show up in a convenient AssetLib search.

PS: It would also be nice if the .blend file could be included in the download. This would make it easier to edit or add animations and change the mesh (for different proportions or body type for example. Someone who downloads the mannequin via AssetLib won't be aware of the availability of the .blend file in the Github releases. Even though I checked the Github page many times before, I only now realised there is a .blend file available when I was reading through some of the other issues here.

Player model vibrates on 144Hz monitor

I'm submitting a...

• Bug report.

Bug report

What is the current behavior?
The player model vibrates while moving on a 144Hz monitor.

What is the expected behavior?
The player model should be moving smoothly.

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.

1. Enter the main 'Game' scene
2. Point camera up into the sky at a steep angle so the effect is more noticeable
3. Run around and rotate camera at same time

Create a basic 3D, 3rd-person character controller with Mannequiny

This is a high-level overview of the project to get the conversation and work started.

Here are our gdscript guidelines: https://www.gdquest.com/open-source/guidelines/godot-gdscript/

Use Mannequiny, our 3d character made by Luciano Muñoz, to create a reusable 3rd person 3d character controller. The asset will end up on the asset library.

High-level requirements

1. The player is able to Walk, run, and jump. The speeds and jump height are configurable in the inspector
2. The character feels responsive: little or no acceleration and deceleration to start and stop moving
3. It uses include a camera rig that can orbit around the character
4. Input: the character is designed for a WASD + mouse, or dual stick with the gamepad, one stick for the character's motion, and one stick to control the camera

The camera

Check https://github.com/jedStevens/ez-camera for reference. You need several nodes do make the camera easy to control.

I'm not sure how the camera should behave exactly yet. Suggestions are welcome on that end. But let us keep it simple enough to start with.

Code structure

As usual, you should aim for clean and flexible code.

1. Create an animation tree character transitions from Idle to walk, run, and jump. You can use the animation state machine from Godot at 3.1 for that
2. Reuse the State machine from the Metroidvania project. Each character actions should be a separate state.
3. The camera is independent of the character: it should run by itself without errors.

Test adding walk and run animations, fading, and analog movement

The right thigh is rotated outwards

There is an issue with the exported animations, or with the import, where the character's thigh is rotated outwards, making the hip joint come out.

player to emeshed in example project for the sake of convienience

I'm submitting a...

• [x ] Bug report.
• x[ ] Feature request.

Bug report

There is a custom input map and numerous other issues that mean you can't simply copy player.tscn into another project

What is the current behavior?
sits there ignoring input generating multiple errors with a bewildering list of signals

What is the expected behavior?
copy player.tscn and player.gd to new project and it work...

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.

Feature request

restructure demo project with the aim in mind to make it more portable between projects

Describe the problem you're trying to solve.

Tell us which solutions you've explored, the solution you would pick, and why you think it would be the best for everyone.

Other

Other information

Use gltf 2.0 for the mesh instead of escn

/!\ Export from Blender 2.81+ and import in Godot 3.2+.

Character stutters and gets locked into Idle/Run states at a certain angle against walls and in corners

Movement speed coupled to camera orientation

I'm submitting a...

• [x ] Bug report.

Bug report

What is the current behavior?
Movement speed is linked to the camera angle. In particular if the camera angle is pointing upwards, the speed is greatly reduced.

What is the expected behavior?
I assume that the speed is meant to be independent of the camera angle.

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.

1. Enter the main 'Game' scene
2. Point the camera into the sky.
3. Run around.

Other

Other information
I have a PR waiting in the wings if this is indeed a bug.

Godot 3.2 release exception

I'm submitting a...

• Bug report.
• Feature request.

Bug report

What is the current behavior?
Version: v0.2.0, as provided on the template list available with the latest godot 3.2 download, exits with exception when run from the editor.

State.gd:18
Trying to assign value of type 'StateMachine.gd' to a variable of type 'State.gd'.

What is the expected behavior?
Not exiting with an exception, I would imagine.

Tell us the steps to reproduce the bug, and if possible share a minimal demo of the problem.
Immediate exception.

1. Run in the UI
2. Immediate exception will be apparent

mannequiny-0.4.0.blend animation is off

The animation model mannequiny-0.4.0.blend animations are slightly messed up. For example, when doing the run animation it swings its lefts comically to the side. Also, its not in the git repository and is a separate download.