Attach To Target for Buildbox 3 + Demo Game

WHAT IS THE PURPOSE OF THIS NODE?
To allow you to easily attach and detach props to animated characters in Buildbox, you can use it to attach and detach a weapon your character's hand, a hat on his head, shoes to his feet and so on.

Here's a clip showing what you can achieve with this node, demo is included in the package.

This node will allow you to create a much deeper level of interaction in your games, it is an absolute must to create point and click adventures, RPG games, action and sports games... imagine the possibilities!

And here's a quick tutorial showing how you can easily use it in your game!

WHAT'S INCLUDED IN THE PACKAGE?
- AttachToTarget.bbnode: the node file you can easily drag&drop inside your Buildbox games.
- Prop Attach Demo.bbdoc: a demo game showing examples of what can be achieved with the AttachToTarget node.
- Readme file with instruction + useful images and links. 

DOES IT WORK WITH ANY MODEL?
The node is designed to work with FBX models coming from Mixamo or rigged with it (www.mixamo.com) since it is a very well established and recognized tool to obtain animated characters; the node is also able to work with FBX models coming from other sources as long as they've been rigged which means they have a skeleton with bones to which objects can be attached.

Here is the skeleton of a model rigged in Mixamo with all the bones names as shown in Blender (www.blender.org). 

HOW TO USE IT?
It is very easy to use, just add the node to a prop then select the target character and an attach point, like the right hand for example.
Now you can have the prop to interact with your character in many ways, let's say for example that there is a gun on the floor, your character will be able to pick it up and hold it in his hand and this can happen in several ways, a few examples:
- when it collides with it: use an 'If collide' node.
- when you tap on it: use an 'Is Touched' node.
- when you press a button: use a UI button.
 You'll find all of these cases in the demo BBDOC!
 These are just a few examples of what you can do.


Here you can see the node attributes and how simple it is to setup it. If touched the hat will attach on top of the head of the target model or detach from it if already attached.

NODE ATTRIBUTES
- Target: the target Character object to which the prop will be attached, MUST contain a Sub Scene node (FBX model).
- Attach Point: a dropdown list with all of the 65 standard attach points (bones) available in most models rigged with Mixamo (www.mixamo.com).
While this would work for many models, please note that not every model on Mixamo uses the same bone structure and names; in such cases you'll
still be able to attach a prop by using the "Alt. attach point" attribute as described in next point.
- Alt. attach point: here you can specify an alternative attach point in case the FBX model you're using wasn't rigged with Mixamo or isn't using the standard bones names used by Mixamo, to discover names you have to check inside the FBX model you're using, for example by opening it in Blender (www.blender.org) and checking bones under "Armature", there you'll find the complete skeleton of the model and the name of each of the bones that are part of it; for example the neck bone in Mixamo might be called "mixamorig:Neck".
- Affected Asset: with this dropdown attribute you'll be able to specify which assets the prop will collide with once it has been attached to the character, you can either select "All", "None", "Enemy", etc. For example for a gun or a sword you might select "Enemy" so that once it is attached to the character it becomes a weapon and collides only with objects in the "Enemy" Collision Group.
- Move/Rotate: when you attach a prop to a character it might be slightly off, maybe you attached a gun to a hand and it's not in the exact position but it is overlapping fingers, to fix this type of problems you can set these values to move and rotate the prop relative to the bone it is attached to.
- Disable Debug Messages: tick to disable error and warning messages.
- Restore Physics Settings after detach: if ticked restores the initial physics settings of the prop after it's been detached from the target. Restores both the physics type (Dynamic, Kinematic, Static or none) and the affected asset (Enemy, Character, None, etc.).
- Restore Position/Rotation/Scale after detach: if ticked restored the initial position/rotation/scale of the prop after it's been detached from the target.

F.A.Q.
Q. The attached object is always static or it disappears, why?
A.  it might be because the attach point is not a valid one or the object has been correctly attached to the attach point but is now hidden by the model mesh.
For more information check "Attach Point" and "Alt. attach Point" in NODE ATTRIBUTES.

TROUBLESHOOTING

ERROR / WARNING MESSAGE	REASON / SOLUTION
ERROR: Target Asset is null!	Make sure you've selected an asset in 'Target' attribute, usually this is the character you want to attach the prop to.
ERROR: Target Asset "..." not found in current scene!	Make sure the 'Target' asset exists in current scene. For example: to attach a gun to your character's hand you have to make sure your character exists in current game scene.
ERROR: Target Asset "..." does not contain a Sub Scene (FBX model)!	The 'Target' asset you've selected exists but does not contain a Sub Scene node.
ERROR: Cannot attach "..." to attach point "..." of target asset "...", check its Sub Scene FBX model in Blender and make sure its skeleton (armature) contains the specified attach point (bone)!	The node wasn't able to attach the prop to the target asset; this usually happens when the attach point doesn't exist. For more information check "Attach Point" and "Alt. attach Point" in NODE ATTRIBUTES.
ERROR: One or more errors occurred! The node won't work properly!	This is only shown when one or more error occur to signal that the node won't work properly.
WARNING: Multiple Sub Scenes found in Target Asset "...", the one named "..." will be used!	The target asset contains multiple Sub Scene nodes (FBX models); in such a case the last one found will be used and the prop attached to it.

SYSTEM REQUIREMENTS
Buildbox 3.4.5 is required to use this node and the included BBDOC.
Tested with Buildbox up to 3.5.7. NOT WORKING ON BUILDBOX 4!
The node and the BBDOC will work no matter the plan you are in (Free, Plus, Pro, etc.).

CHANGELOG
1.0.0 (March 31, 2021): First public release.
1.0.1 (April 6, 2021): Improved error checking and messages.
1.0.2 (April 9, 2021): Fixed two bugs causing scale and color of prop to reset after being detached from Target Character.
1.1.0 (January 16, 2022): Detach now works better and is able to save physics settings, position, rotation and scale of the prop when attached to the character and restore after detach. Also fixed bug causing wrong colors when detaching props made up of several 3D Models.

Looking for a developer to help you with your Buildbox project? Hire me!

COPYRIGHT NOTICE & LICENSE AGREEMENT
Please note that this asset package and all of its content, including source code, is protected by copyright, it is not open source.
In short you can use it in any of your Buildbox projects but please don't share it, it took a lot of effort to design, create and optimize it.
In detail here's a more exhaustive copyright notice for this asset package, please read it carefully, thank you!
Once purchased you are free to use the asset package within your personal and commercial Buildbox projects.
And of course you are free to publish, sell or otherwise distribute any app or software you export from Buildbox that makes use of any of the assets in this asset package.
You are not allowed to allow users of such apps or softwares you created to access, extract and/or use any of the assets included in this package outside of the software, for example you are not allowed to distribute a Buildbox template or asset which includes any content coming from this asset package.
For sublicensing, volume licensing or any other request please contact me!
You are not allowed to copy, sell, give away or otherwise distribute any of the assets contained in this asset package, either in their original form or in any modified form. You are not allowed to remove this copyright notice.

Looking for a developer to help you with your Buildbox project? Hire me!