| object - a custom Type object, or Null |
|
Turns a Type object into a plain integer that identifies it. Type objects are the things you make with New - a monster, a bullet, a save slot. They are wonderful inside your program and useless outside it: you cannot write one into a file, stuff it into a bank, or send one over the network. Handle solves that by giving each object a small integer of its own, and Object turns the integer back into the object later. The number is stable: ask for the same object's handle a hundred times and you get the same answer every time. Numbers start at 1 and only ever count upwards, so a fresh object never reuses a retired number. Handle of Null is always 0, which makes 0 a natural "nobody" value for an empty slot in a bank or a network packet. Typical uses are a save file that records which monster a quest was pointing at, a network message that says "the object with id 7 just died", and a bank of enemy ids that a particle effect can consult without holding a real reference. It is also the cheapest way to print something identifying about an object while debugging. Two gotchas. Handles are only meaningful inside the run that made them - they are not stable from one launch of your game to the next, so a save file that stores raw handles must rebuild its own mapping on load rather than trusting the numbers. And once you Delete the object, its handle no longer resolves: Object answers Null for it. That is actually useful, because it turns a stale id into a safe, detectable miss instead of a crash. Handle is a compiler special form rather than an ordinary function, so it is written straight in front of the object - Handle m and Handle(m) both work. It cannot be used inside a Worker Function; jobs run on their own thread and are not allowed to touch the object tables. See also: Object, New, Delete, Each, Type. |
; Handle Example
; --------------
; A tiny monster roster - the sort of list a game keeps for its enemies
Type Monster
Field name$
Field hp
End Type
For i=1 To 3
m.Monster=New Monster
m\name="Goblin "+i
m\hp=i*10
Next
; Handle turns a Type object into a plain integer. That number can go
; into a save file, a bank or a network message - places a Type object
; itself cannot travel.
Print "Roster:"
For m.Monster=Each Monster
Print " "+m\name+" hp "+m\hp+" handle "+Handle(m)
Next
Print ""
; Asking for the same object twice always gives the same number
boss.Monster=Last Monster
Print "Same object asked twice : "+Handle(boss)+" then "+Handle(boss)
; A Null object always handles to 0, so 0 is a safe "nobody" value
nobody.Monster=Null
Print "Handle of a Null object : "+Handle(nobody)
Print ""
; Object turns the number back into the object again
saved=Handle(boss)
back.Monster=Object.Monster(saved)
Print "Object.Monster("+saved+") is "+back\name
; After the object is deleted the same number resolves to Null, which
; is a cheap way to spot a reference that has gone stale
Delete boss
gone.Monster=Object.Monster(saved)
If gone=Null Then Print "After Delete, handle "+saved+" gives Null"
Print ""
Print "Press any key to close the example"
WaitKey
End