Script objects and Dynamic objects

Script objects are used when game entities have to be registered for being referable from script. They do support reference counting so that if there's still existing reference in the script, script object won't be destroyed and could be referenced without causing error.

Registering entities for script

Script object is registered via ccRegisterManagedObject() function. In such cases when that is impossible or unwanted to allow script refer to the entity directly by address, a simple auxiliary struct is used, that holds entity's ID; that struct is registered in script system instead of entity object.

For example, for Character entities CharacterInfo objects are registered themselves. Opposite to that, it is not always correct to reference InventoryItemInfo directly, since amount of inventory being held by character is not represented by instances of InventoryItemInfo class. Therefore objects of ScriptInvItem that hold inventory IDs are registered instead.

Dynamic objects

When the object is registered for script via ccRegisterManagedObject() function it is accompanied by a pointer to Dynamic Object. This object is used to further manage the registered script object. The Dynamic Object can be of type, derived from class ICCDynamicObject, or, usually, of its direct descendant - class AGSCCDynamicObject. A note should be made that script object and its managing object may be actually the same.

ICCDynamicObject is an abstract interface, which declares methods for:

1. GetType() for getting entity type;
2. Dispose() for disposing (safely destroy) the script object;
3. Serialize() for serializing the script object (writing its data to the stream).

AGSCCDynamicObject adds additional virtual function Unserialize() for reading serialized script object data back, and provides default implementations for disposing and serializing it.

In AGS there is a distinction between entities that are created when game runs (strings, dynamic sprites, overlays, opened files) and the entities which number is defined at game start and never changed (characters, room objects and hotspots, and so forth). Therefore their management is different.

Dynamically created entities are represented by classes derived from ICCDynamicObject. When registered, these objects are used both as a script object and management object, in other words they manage themselves. Examples are: ScriptDateTime, ScriptDrawingSurface, ScriptDynamicSprite.

Precreated entities (usually objects that are stored in static C arrays) are represented by their own related classes not derived from ICCDynamicObject. These classes have managing counterparts. For example, class CharacterInfo is paired by CCCharacter class. InventoryItemInfo has an auxiliary struct ScriptInvItem, which is managed by CCInventory class.

When being disposed by memory management system these script objects are deleted.

The destruction of script object does not necessarily mean that underlying entity object is physically removed from memory. In some cases that's true, in others entity objects are not deallocated, but considered "unused". They may be used later to represent newly created entity. This depends on how actual data storage is implemented in program.

Conclusion

The scheme that is being used to bind game entity with script:

Game Entity <------> Script Object [ + manager-helper Dynamic Object ]

In brief, a script object provides reference to entity from script. It is kept registered so far as reference must exist. When no longer needed, it is disposed from memory management system. That means it is no longer considered existing in script, but it may or may not be physically deleted in the engine, depending on particular object's implementation.

The data used to store game entity too may or may not be physically deleted, but that's something that engine should care about and not script system.

The script object and helper dynamic object may be the same object, or they may be two different ones. One dynamic object could be used to manage numerous script objects. Game entity object could be at the same time script object, and, in rare cases, dynamic object too.