Blitz3D+ Command Reference

LoadAnimMesh ( file$[,parent] )

Parameters

file$ - model file to load
parent (optional) - entity to parent the loaded model to; 0 (default) for none

Description

Loads a model keeping its hierarchy and animation, and returns the handle of its root entity, or 0 if the file could not be loaded.

This is the command for characters, vehicles with moving parts, and anything else that has to bend, walk or open. Where LoadMesh flattens a file down into a single mesh, LoadAnimMesh keeps the node tree the artist built and all the animation data that goes with it, so you can play the animation with Animate or PlayAnim and reach into the model afterwards.

The recognised formats are .b3d, .x, .3ds, .gltf and .glb. Skinned characters and named animation clips come through best in .b3d, .gltf and .glb.

What you get back is the root of a tree, not a single mesh. Use FindChild and GetChild to grab a named part - a turret, a door, a hand - and move it independently, and CountBones, GetBone and FindBone to reach the skeleton. AttachToBone is the tidy way to put a weapon in a character hand. Because the root is usually an empty pivot rather than a mesh, per-vertex commands like VertexCoords need the child mesh, not the handle returned here.

The optional parent makes the model a child of another entity, so moving the parent moves the model; the relationship is one way, and the model still starts at 0,0,0 in the parent local space rather than at the parent position.

See also: LoadMesh, Animate, PlayAnim, LoadAnimSeq, FindChild, FindBone.

Example

; LoadAnimMesh 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")

; LoadAnimMesh keeps the file's hierarchy and animation data, unlike
; LoadMesh which collapses everything into a single static mesh
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

; The retained animation can be played straight away
walk=FindAnimSeq(fox,"Walk")
Animate fox,1,1,walk

While Not KeyDown(1)

    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,"Arrows: camera   Esc: exit"
    Text 0,20,"LoadAnimMesh kept the skeleton: "+CountBones(fox)+" bones, "+AnimLength(fox)+" tick walk cycle"

    Flip

Wend

End

Index