Object IDs are a feature unique to SkookumScript – they allow game / simulation objects, concepts and assets to be referred to by class type and name in code.
Object IDs can be used for game characters, trigger regions, sound effects, user interface elements, mission names, cars, cutscenes, props, doors, geographical locations, art assets, game events, AI / behaviour types, animations or anything that you can associate a name to.
Classes that use object IDs must have the appropriate settings in their class meta file and a
object_id_find() method that can be called to do object lookup.
Actor objects have object IDs enabled and by default look them up by name using the
Using Object IDs in Code
Every object ID is associated with a SkookumScript class type. If the class type is not specified then the
Actor class is inferred.
Object IDs have several forms:
- Reference @: refers to the named object
- Potential reference @?: refers to the named object or
nilif not found
- Identifier @#: identifier name of the object in the type most appropriate for the runtime
Object IDs Cache References to Objects
If a reference or potential reference form of an object ID is evaluated, it caches the reference of the object (using a memory smart pointer) and will quickly return the same object on successive calls if the object is still valid. It will only look up the object by name again if the previous object goes stale and is removed for some reason.
This means that they can be more speed efficient than a routine call that does a look-up each time it is evaluated.
The reference form of an object ID uses an “at” symbol
@. It returns a reference to the named object and will assert if the named object is not present when the object ID is evaluated. Its result class type is the same as the class doing the named object lookup. So
Mission@'crazy_space_chase' will have a result class type of
// Actor is inferred @'SomeGuy'.do_stuff // Same as above Actor@'SomeGuy'.do_stuff // Similar to above though in method // form and result not cached Actor.named("SomeGuy".Name).do_stuff
Potential Reference @?
The potential reference form of an object ID uses an “at” symbol
@ followed by a question mark
?. It returns a reference to the named object or
nil if the object is not present when the object ID is evaluated. Its result class type is a union between the object ID class and
None (the class type for
Trigger@'trap_door' will have a result class type of
// Actor is inferred so <Actor|None> is result type @?'SomeGuy' // Same as above Actor@?'SomeGuy' // Similar to above though in method // form and result not cached Actor.named("SomeGuy".Name) // Generally need to account for possibility of nil !guy: @?'SomeGuy' guy.do_stuff unless guy.nil? // [or] Use apply operator % to ignore call if receiver is nil @?'SomeGuy'%do_stuff
The identifier form of an object ID is essentially the same as a common identifier type of the engine being used (
Name in UE4 or
FName in UE4 C++). It uses an “at” symbol
@ followed by a hash sign
#. It returns a
Symbol. It is useful to use in code that need to reference the name of an object and do not need the object itself.
// Actor is inferred and engine identifier type is result @#'SomeGuy' // Same as above Actor@#'SomeGuy' // Similar to above "SomeGuy".Name // Can be used with methods that need the name of an object my_mission.set_smart_mouth(Robot@#'Marvin')