Blitz3D+ Command Reference

AttachToBone ( entity,animated_entity,bone_name$[,global] )

Parameters

entity - entity to attach
animated_entity - handle of the animated entity that owns the skeleton
bone_name$ - bone name, or a slash-separated path through the skeleton
global (optional) - True to keep the attached entity current world position and rotation; False (default)

Description

Attaches an entity to a named bone of an animated model, and returns the bone handle.

This is how a weapon ends up in a hand, a hat on a head, a torch in a fist or a muzzle-flash pivot on the end of a barrel. The attached entity becomes a child of the bone, so it follows every twitch of the animation with no work from you.

The global parameter decides how the attachment is made. With False, the default, the entity keeps its local position and rotation, so an entity sitting at 0,0,0 lands exactly on the joint - then nudge it into place with PositionEntity and RotateEntity relative to the bone. With True, the entity holds the world position and rotation it has right now, which is what you want when something already lined up in the world needs to start following a character without jumping.

The bone is looked up the same way FindBone does it: exact name first, then case-insensitively, with a slash-separated path such as "Spine/Neck/Head" available when names repeat. A name that matches nothing raises an error naming the bone it could not find, which makes typos easy to spot.

To detach later, just reparent the entity normally with EntityParent - there is no special detach command.

See also: FindBone, CountBones, GetBone, EntityParent, LoadAnimMesh.

Example

; AttachToBone Example
; --------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,2,-6
RotateEntity camera,12,0,0

light=CreateLight()
RotateEntity light,45,45,0

; A grassy paddock for the fox to roam
ground=CreatePlane()
EntityTexture ground,LoadTexture("media/MossyGround.BMP")

; Load the rigged fox; its skinned mesh is driven by a bone skeleton
fox=LoadAnimMesh("../../../samples/glTF/assets/Fox/Fox.glb")
If fox=0 Then RuntimeError "Could not load Fox.glb: "+ModelLoadError()

; Shrink the fox to game scale (the file is modelled about 100 units tall)
FitMesh fox,-0.8,0,-0.8,1.6,1.6,1.6,True

; A glowing lantern for the fox to carry
lantern=CreateSphere(8)
ScaleEntity lantern,0.08,0.08,0.08
EntityColor lantern,255,220,60
EntityFX lantern,1

; AttachToBone parents the lantern to the fox's right hand bone, so the
; walk and run animations swing it around like a carried prop
If AttachToBone(lantern,fox,"b_RightHand_08")=0 Then RuntimeError "Hand bone not found"

; Small local offset from the bone
PositionEntity lantern,0,0.1,0

; Start the fox walking
PlayAnim fox,"Walk",0

While Not KeyDown(1)

    ; Switch clips to see the lantern follow the hand in each one
    If KeyHit(2) Then PlayAnim fox,"Survey",10
    If KeyHit(3) Then PlayAnim fox,"Walk",10
    If KeyHit(4) Then PlayAnim fox,"Run",10

    UpdateWorld

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"1/2/3: Survey/Walk/Run   Arrows: camera   Esc: exit"
    Text 0,20,"AttachToBone fixed the yellow lantern to bone "+Chr$(34)+"b_RightHand_08"+Chr$(34)

    Flip

Wend

End

Index