Blitz3D+ Command Reference

LoadGLTFScene ( file$[,parent] )

Parameters

file$ - path of the .gltf or .glb file to load

parent (optional) - entity to parent the loaded scene to; 0 for no parent (default)

Description

Loads a glTF or GLB file as a complete entity tree, keeping its node hierarchy.

LoadMesh flattens everything it finds into one lump of triangles, which is perfect for a crate and wrong for a level. LoadGLTFScene does the opposite: every node in the file arrives as its own entity, parented exactly the way the artist built it. You get back the root, and from there CountChildren, GetChild, FindChild and EntityName let you walk the whole thing - so the door your artist named "Door_01" is a real entity you can rotate, the wheels are separate from the chassis, and a light rig stays a light rig.

That is what makes it the command for loading a level, a prop set or a vehicle out of one file. Attach the result to a pivot with the parent argument and you can position, scale and spin the entire scene as a unit while still reaching individual parts underneath. Materials, textures and node transforms all come across; animations come with it too, so if the file is animated you can drive it with the usual Animate and PlayAnim commands on the root.

Cameras authored in the file are imported, but the loader deliberately hands them over switched off - each one is given the current viewport, then hidden and disabled so it cannot quietly take over your view the moment the scene loads. If you actually want the artist's framing, ShowEntity on that camera activates it; HideEntity puts it back to sleep. Your own camera keeps working exactly as before either way.

Watch the scale. glTF is a real-world-units format, so a car exported from a modelling package may genuinely be 0.2 units long and vanish inside your near clip plane. Load it under a pivot and scale the pivot, rather than trying to fight the numbers per part.

On failure the return value is 0 and nothing is added to the world - always check for that and print ModelLoadError to find out why. Note that a node named like a camera is not necessarily a camera: EntityClass tells you what each child really is.

Requires Extended mode.

See also: LoadMesh, LoadAnimMesh, ModelLoadError, EntityClass, CountChildren, FindChild.

Example

; LoadGLTFScene Example
; ---------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,1.5,-6

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

; A pivot to hang the imported scene on, so we can scale and spin it as one
holder=CreatePivot()

; The whole file arrives as one entity tree, parented to our pivot
scene=LoadGLTFScene("../../../samples/glTF/assets/ToyCar/ToyCar.glb",holder)
If scene=0 Then RuntimeError "Could not load ToyCar.glb: "+ModelLoadError()

; The car is authored at real-world scale, about 20cm long
ScaleEntity holder,30,30,30

; Every node of the file became a child entity you can address by yourself
parts=CountChildren(scene)
pick=1

While Not KeyDown(1)

    TurnEntity holder,0,0.4,0

    ; Space steps through the parts the file was built from
    If KeyHit(57) And parts>0
        ; Put the old selection back to full opacity
        old=GetChild(scene,pick)
        If EntityClass(old)="Mesh" Then EntityAlpha old,1
        pick=pick+1
        If pick>parts Then pick=1
    EndIf

    ; Describe whichever part is selected, and fade it so you can spot it
    part=GetChild(scene,pick)
    name$=EntityName$(part)
    cls$=EntityClass(part)
    surfs=0
    If cls$="Mesh"
        surfs=CountSurfaces(part)
        EntityAlpha part,0.3
    EndIf

    ; 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,"Space: step through the imported parts   Arrows: camera   Esc: exit"
    Text 0,20,"LoadGLTFScene(...,holder) gave one root entity with "+parts+" children"
    Text 0,40,"Part "+pick+" of "+parts+": "+Chr$(34)+name$+Chr$(34)+"   class "+cls$+"   surfaces "+surfs
    Text 0,60,"The faded part is the selected one. Helper nodes carry no geometry at all"

    Flip

Wend

End

Index