Blitz3D+ Command Reference

ModelLoadError$ ( )

Parameters

None.

Description

Returns the reason the last model load failed, or an empty string if it worked.

LoadMesh, LoadAnimMesh, LoadGLTFScene and friends all report failure the same unhelpful way: they hand back 0. That is fine when you are testing your own game on your own machine and you already know the file is missing, and useless the moment somebody else runs it. ModelLoadError is the missing half of that conversation - call it straight after a load that returned 0 and you get a sentence naming the file and saying what went wrong.

Messages look like B3D model 'crate.b3d': file is missing or unreadable, glTF 'hero.glb': glTF source is missing or unreadable: hero.glb or Unsupported model format '.jpg': media/logo.jpg. That is enough to tell a typo from a path problem from someone dropping the wrong file into the media folder, which is exactly what you want in a shipped game's error message.

The standard pattern is one line under every load:

hero=LoadAnimMesh("media/hero.glb")
If hero=0 Then RuntimeError "Could not load hero.glb: "+ModelLoadError()

There is one string, shared by every model command, and it holds the result of the most recent load attempt - so read it immediately. Loading anything else in between overwrites it. A successful load clears it to "", which also means an empty string on its own is not evidence that a load succeeded: check the handle first, then ask why.

Requires Extended mode.

See also: LoadMesh, LoadAnimMesh, LoadGLTFScene, LoadBSP, LoadTexture.

Example

; ModelLoadError Example
; ----------------------
; Requires Extended mode.

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

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

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

; A stand-in prop that spins while no model has been loaded
placeholder=CreateSphere(12)
ScaleEntity placeholder,0.4,0.4,0.4

; Start with a deliberate failure so there is a message to read straight away
tried$="media/no_such_model.b3d"
model=LoadMesh(tried$)
; ModelLoadError reports the last loader failure, or "" after a success
why$=ModelLoadError()

While Not KeyDown(1)

    ; 1 a real model, 2 a file that is not there, 3 a file that is not a model
    want$=""
    If KeyHit(2) Then want$="media/oil-drum/oildrum.3ds"
    If KeyHit(3) Then want$="media/no_such_model.b3d"
    If KeyHit(4) Then want$="media/b3dlogo.jpg"

    If want$<>""
        If model<>0 Then FreeEntity model
        tried$=want$
        ; LoadMesh just returns 0 when it fails - it never says why
        model=LoadMesh(tried$)
        why$=ModelLoadError()
        If model<>0 Then FitMesh model,-1,0,-1,2,2,2,True
    EndIf

    ; Show the placeholder only while there is no model to look at
    If model=0
        ShowEntity placeholder
    Else
        HideEntity placeholder
    EndIf

    TurnEntity placeholder,0,1.5,0
    If model<>0 Then TurnEntity model,0,0.6,0

    ; 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: real model   2: missing file   3: not a model   Arrows: camera   Esc: exit"
    Text 0,20,"LoadMesh("+Chr$(34)+tried$+Chr$(34)+") = "+model
    If why$=""
        Text 0,40,"ModelLoadError() = "+Chr$(34)+Chr$(34)+"  - empty, so that load worked"
    Else
        Text 0,40,"ModelLoadError() = "+why$
    EndIf
    Text 0,60,"Print this string when a load fails and you know exactly what broke"

    Flip

Wend

End

Index