Creatures 2 provides an OLE DispatchInterface which allows external programs to communicate with the game. This allows access from most of the programming languages currently available for Windows development.
The interface is described by the following ODL file:
[ uuid(22582D65-4EE0-11d1-8791-0060B07BFA18), version(1.0) ] library SmallFurryCreatures { importlib("stdole32.tlb"); [ uuid(22582D66-4EE0-11d1-8791-0060B07BFA18) ] dispinterface ISFC { properties: methods: [id(1)] boolean RequestMacro(VARIANT* p_Variant1, VARIANT* p_Variant2); [id(2)] boolean ExecuteMacro(VARIANT* p_Variant1, VARIANT* p_Variant2); [id(3)] boolean CreateMacro(VARIANT* p_Variant1, VARIANT* p_Variant2); [id(4)] boolean DestroyMacro(VARIANT* p_Variant1, VARIANT* p_Variant2); [id(5)] boolean LoadMacro(VARIANT* p_Variant1, VARIANT* p_Variant2); [id(6)] long CreateCommand(short Type); [id(7)] boolean DestroyCommand(long Cmd); [id(8)] void LoadCommand(long Cmd, BSTR String); [id(9)] boolean RequestCommand(long Cmd, BSTR* Data); [id(10)] boolean FireCommand(short Type, BSTR Cmd, BSTR* Data); }; [ uuid(22582D67-4EE0-11d1-8791-0060B07BFA18) ] coclass OLE { [default] dispinterface ISFC; }; }; |
This ODL file can be used to generate interfacing code for the Windows programming language of your choice Many development environments can perform this step automatically.
Most of the defined methods are only supported for historical reasons. The only one currently in use is FireCommand(). This sends a CAOS macro to the game for execution and returns any resultant text. Its parameters are:
Type: This should always be set to 1 (again, this is here for historical reasons).
Cmd: A CAOS macro string to execute (eg "dde: getb cnam" to get the current creatures name).
Data: Results are returned here as text.
FireCommand() returns FALSE if an error occurs.
The DispatchInterface for Creatures 2 is called "SFC2.OLE".
Listening to Creatures 2
Creatures 2 also has the capability to send out notifications when certain events occur for example, changing the subject creature, pausing the game
An OLE DispatchInterface is, again, used to implement this. However, this time the interface is provided by the external application rather than the game.
Here is an example ODL file to describe this interface (from the observation kit):
// ObservationKit.odl : type library source for ObservationKit.exe
[ uuid(DADE5D24-86BA-11D1-BA2F-0060084C69DB), version(1.0) ] library ObservationKit { importlib("stdole32.tlb"); [ uuid(DADE5D25-86BA-11D1-BA2F-0060084C69DB) ] dispinterface IObservationKit { properties: methods: [id(1)] boolean Communicate(VARIANT* pVariant1, VARIANT* pVariant2); }; [ uuid(DADE5D23-86BA-11D1-BA2F-0060084C69DB) ] coclass ObservationKit { [default] dispinterface IObservationKit; }; }; |
Only one method is defined: Communicate().
When the game calls Communicate(), the lVal field of pVariant1 contains a 32 bit value which should be interpreted as 4 separate bytes. The notification is encoded in one or more of these bytes:
Byte 0 | Byte 1 | Meaning | Byte 2 (if used) |
1 | 1 | CLOSE a request for the applet to shut down. | |
1 | 2 | BRING_TO_TOP | |
1 | 3 | YOUR_ID_IS This message is sent to the applet upon startup. AppID is a unique identifier which the game has allocated. | AppID |
2 | 6 | SUBJECT_CHANGED a new Creature has been selected. | |
2 | 7 | SUBJECT_RENAMED | |
2 | 8 | SUBJECT_DIED | |
2 | 9 | SUBJECT_AGED Creature has advanced a life stage. | |
2 | 10 | PAUSE_GAME called whenever the game is paused or unpaused. | PauseState |