Blitz3D+ Command Reference

Object.TypeName ( handle )

Parameters

TypeName - the custom Type you expect to get back, written after the dot

handle - integer previously returned by Handle

Description

Turns an integer handle back into the Type object it came from.

Object is the other half of Handle. Handle flattens an object down to a number so it can live in a save file, a bank or a network message; Object takes that number and gives you the real object again, ready to follow with \ field access.

The Type name is part of the syntax, not a parameter you can compute - you write Object.Monster(id) because the compiler has to know at build time what kind of object the expression produces. Blitz3D+ also accepts the modern spelling Object:Monster(id) in Extended mode; both mean the same thing.

Every kind of miss answers Null instead of raising an error, which is exactly what you want when the number came from somewhere you do not control. A number that was never a handle, a handle belonging to a different Type, and a handle whose object has since been Deleted all give Null. So a save file full of nonsense cannot crash your loader, and a network message about a monster that died two frames ago quietly resolves to nothing. Always test the result against Null before following it.

In a game this is the pattern behind "which object is this message about". The server sends the handle of the target, the client calls Object on it, and if the answer is Null the target is already gone and the message is dropped. It is also a neat dangling-reference check while debugging: keep the handle, and any time Object returns Null you know the object was deleted underneath you.

Two restrictions. The Type must be a real custom Type - an Interface is not concrete enough for the compiler to build the cast. And, like Handle, Object cannot be used inside a Worker Function, because jobs run on their own thread away from the object tables.

See also: Handle, New, Delete, Each, Type.

Example

; Object Example
; --------------

; Two kinds of thing, so we can show what a handle does when it is
; handed to the wrong Type
Type Turret
    Field label$
    Field ammo
End Type

Type Crate
    Field label$
End Type

t.Turret=New Turret
t\label="North turret"
t\ammo=40

c.Crate=New Crate
c\label="Ammo crate"

; Handle gives us plain integers we could write to a save file
turret_id=Handle(t)
crate_id=Handle(c)
Print "turret handle "+turret_id+"   crate handle "+crate_id

Print ""

; Object turns an integer back into the object it came from. The Type
; name after the dot tells the compiler what it is getting back.
back.Turret=Object.Turret(turret_id)
Print "Object.Turret(turret handle) -> "+back\label+", ammo "+back\ammo

Print ""

; Every miss answers Null rather than raising an error, so a handle
; from an untrusted save file can never crash you.

; The crate's handle is a real handle, but not a Turret
wrong.Turret=Object.Turret(crate_id)
If wrong=Null Then Print "Object.Turret(crate handle)  -> Null (wrong Type)"

; A number that was never a handle at all
never.Turret=Object.Turret(999999)
If never=Null Then Print "Object.Turret(999999)        -> Null (unknown handle)"

; A handle whose object has since been deleted
Delete c
stale.Crate=Object.Crate(crate_id)
If stale=Null Then Print "Object.Crate(deleted crate)  -> Null (already gone)"

Print ""
Print "Always test the result against Null before following it."

Print ""
Print "Press any key to close the example"
WaitKey

End

Index