WME interface classes

The plugin interface provides a number of interface classes to allow the plugin to access the engine internal classes.

All these classes are declared in the wme_plugin.h header file, which can be found in the WME installation directory in the "plugin\include" subfolder.


IWmeObject class

This class encapsulates a generic WME object, such as scene, entity, actor, sprite etc. Using this class you can call the scripting methods of the object and set/get its scripting properties. For example, you can invoke the "Talk" method of an actor object, or set its "Caption" property.

Supported methods:

bool SendEvent(const char* EventName)

This method is equivalent to the ApplyEvent script method. It sends a specified event to the object.

IWmeValue* CallMethod(const char* MethodName, IWmeParamSet* Params=NULL)

This method invokes a scripting method of the object. You pass a method name and an IWmeParamSet object containing the method parameters. It returns an IWmeValue object containing the return value of the method.

bool SetProperty(const char* PropName, IWmeValue* Value)
bool SetProperty(const char* PropName, int Value)
bool SetProperty(const char* PropName, const char* Value)
bool SetProperty(const char* PropName, double Value)
bool SetProperty(const char* PropName, bool Value)
bool SetProperty(const char* PropName, IWmeObject* Value)
bool SetProperty(const char* PropName)

These methods are used to set a scripting property of the object. You pass them a property name and a value. There are several overrides of this method accepting various types for your convenience.

IWmeValue* GetProperty(const char* PropName)

This method is used to query a value of a scripting property of the object. You pass it a property name and it returns an IWmeValue object containing the value.

void* GetInterface(const char* ClassName)

This method is used to cast a generic IWmeObject pointer to a derived class pointer. The "ClassName" parameter must be a valid name of a class derived from IWmeObject, i.e. either "IWmeGame" or "IWmeSubFrame". It's NOT safe to simply cast the pointer, always use this method instead.


IWmeGame class

This class encapsulates the one and only Game object, i.e. the game "session". It inherits all the methods of IWmeObject and adds several others:

IWmeValue* CreateValue()

This method is used to create a new IWmeValue object.

bool DeleteValue(IWmeValue* Value)

This method deletes an IWmeValue object returned by CreateValue() method.

IWmeParamSet* CreateParamSet()

This method is used to create a new IWmeParamSet object. You are required to delete this object when you no longer need it by calling DeleteParamSet().

bool DeleteParamSet(IWmeParamSet* ParamSet)

This method deletes an IWmeParamSet object returned by CreateParamSet() method.

bool SubscribeEvent(IWmeObject* Object, EWmeEvent Event)

Using this method the plugin object can direct the engine to send events of a given type whenever they occur. You pass it a reference to the WME object owning this plugin object and the event type you want to be receiving.

bool UnsubscribeEvent(IWmeObject* Object, EWmeEvent Event)

As opposed to the SubscribeEvent() method, this method unsubscribes the event.

IWmeFile* OpenFile(const char* Filename)

This method is used to access files using the WME file system. You pass it a filename and it returns a reference to the IWmeFile object (or NULL of the file cannot be opened).

bool CloseFile(IWmeFile* File)

This method closes a file previously opened by the OpenFile() method.

IWmeObject* CreateObject(const char* ClassName, IWmeParamSet* Params=NULL)

Using this method you can create instances of WME's scripting classes, both built-in classes, such as String, Array, Date etc. and classes defined by plugins. Objects created this way are subject to garbage collecting, which means they are automatically destroyed when there are no more references to the object.


IWmeValue class

This class encapsulates variant values used by WME scripting system. The value can contain one of the following types:

Additionally each value can work as an associative array and can contain other IWmeValue objects referenced by their name (properties).

Supported methods:

int GetValInt()
const char* GetValString()
double GetValFloat()
bool GetValBool()
IWmeObject* GetValNative()

These methods return the value contained in the IWmeValue object and convert them to the requested return type if necessary.

bool SetVal(int Value)
bool SetVal(const char* Value)
bool SetVal(double Value)
bool SetVal(bool Value)
bool SetVal(IWmeObject* Value)
bool SetVal(IWmeValue* Value)
bool SetVal()

These methods are used to assign a value to the IWmeValue object.

bool IsValInt()
bool IsValString()
bool IsValFloat()
bool IsValBool()
bool IsValNative()
bool IsValObject()
bool IsValNull()

These methods return true of the object currently contains value of a given type.

IWmeValue* GetProperty(const char* PropName)

This method is used to query a property of a given name.

bool SetProperty(const char* PropName, int Value)
bool SetProperty(const char* PropName, const char* Value)
bool SetProperty(const char* PropName, double Value)
bool SetProperty(const char* PropName, bool Value)
bool SetProperty(const char* PropName, IWmeObject* Value)
bool SetProperty(const char* PropName, IWmeValue* Value)
bool SetProperty(const char* PropName)

These methods are used to set a property of a given name.


IWmeParamSet class

This class is used to pass parameters to script functions. It's basically a container holding zero or more values (IWmeValue objects). You can create an instance of IWmeParamSet class using the IWmeGame::CreateParamSet() method.

Supported methods:

bool Clean()

This method removes all values currently contained in this param set. Call this method when you need to reuse the IWmeParamSet object for another method call.

bool AddParam(int Value)
bool AddParam(const char* Value)
bool AddParam(double Value)
bool AddParam(bool Value)
bool AddParam(IWmeObject* Value)
bool AddParam(IWmeValue* Value)
bool AddParam()

These methods are used to add a new value of a given type to the param set.


IWmeStack class

This class encapsulates a WME stack object. WME uses stacks to pass parameters when it invokes a method of your plugin object. The plugin method, in-turn, uses the stack to store the return value.

Supported methods:

IWmeValue* PopValue()

This method pops a value from the top of the stack.

bool PushValue(int Value)
bool PushValue(const char* Value)
bool PushValue(double Value)
bool PushValue(bool Value)
bool PushValue(IWmeObject* Value)
bool PushValue(IWmeValue* Value)
bool PushValue()

These methods are used to push a value of a given type to the stack.

bool ExpectParams(int NumParams)

Since users are not guaranteed to pass the correct number of parameters to your methods, you must use this method to correct the number of parameters on top of the stack. If there are too many parameters, the extra ones are removed. If there are too few parameters, NULL values are added. You have to always call this method before reading parameters from the stack.


IWmeSerialMgr class

This class is used for serializing/deserializing the object state when saving/restoring game. Imagine the serialization manager as a buffer which contains a set of values. When saving the game, you put all the member variables of your class to the buffer and when restoring game you read them back. Remember you have to read and write exactly the same amount of data or the saved game gets corrupted and the engine will crash when loading it.

Supported methods:

bool IsSaving()

This method returns true if the engine is saving game or false if the engine is loading game.

bool GetBuffer(unsigned char* Buffer, int Size)

This method reads a specified amount of bytes from the saved game.

bool PutBuffer(unsigned char* Buffer, int Size)

This method writes a specified amount of bytes to the saved game.

bool TransferValue(IWmeGame** Value)
bool TransferValue(IWmeObject** Value)
bool TransferValue(IWmeSubFrame** Value)
bool TransferValue(int* Value)
bool TransferValue(unsigned char* Value)
bool TransferValue(float* Value)
bool TransferValue(double* Value)
bool TransferValue(bool* Value)

These convenience methods allow you to store/restore values of various basic types. If you need to store/restore other types, you need to use the GetBuffer() and PutBuffer() methods. Also note that there's no function for storing/restoring strings, because the memory for the string needs to be allocated by the plugin. There is a method for storing/restoring strings in the plugin helper library though.


IWmeScript class

This class encapsulates WME script objects. It allows you to report runtime errors from within your plugin methods and also setting/getting script variable values.

Supported methods:

const char* GetFilename()

This method returns the filename of the script.

int GetCurrentLine()

This method returns the current line the script is executing.

void ReportRuntimeError(const char* Description)

This method can be used to report a runtime error from within the script.

IWmeValue* GetVariable(const char* VarName)

This method returns the value contained in a variable of a given name.

bool SetVariable(const char* VarName, int Value)
bool SetVariable(const char* VarName, const char* Value)
bool SetVariable(const char* VarName, double Value)
bool SetVariable(const char* VarName, bool Value)
bool SetVariable(const char* VarName, IWmeObject* Value)
bool SetVariable(const char* VarName, IWmeValue* Value)
bool SetVariable(const char* VarName)

These methods are used to assign value to script variables.


IWmeFile interface

This class allows you to read files using the WME's file system. That means you can read even from files stored in WME packages. You can use it for example to read parameters of your plugin object from a game package. To open a file use the IWmeGame::OpenFile() method. To close a file use the IWmeGame::CloseFile() method.

Supported methods:

unsigned long ReadData(unsigned char* Buffer, unsigned long NumBytes)

This method is used to read a specified amount of bytes from the file. It returns the number of bytes actually read.

unsigned long GetFileSize()

This method returns the size of the file.

unsigned long GetFilePosition()

This method returns the current reading position in the file.

bool SeekToPosition(unsigned long Position)

This method sets the reading position in the file.


IWmeSubFrame class

This class encapsulates WME sub-frame objects. It allows you to perform pixel operations directly on images assigned to sprite subframes. Note that any changes to subframes pixels are NOT saved to saved games, which means you'll have to either handle the "update" event and update the subframe periodically, or you'll have to catch the "before save" and "after load" events.

Supported methods:

bool StartPixelOperations()

This method prepares the subframe for pixel operations. It must be called prior to any SetPixel() and GetPixel() calls.

bool EndPixelOperations()

This method must be called after performing a batch of SetPixel() / GetPixel() calls.

unsigned long GetPixel(int X, int Y)

This method returns a color value of a pixel at given coordinates. The color is an RGBA value encoded in a single long integer. You can use the convenience functions in the helper library to extract individual color components.

bool PutPixel(int X, int Y, unsigned long Pixel)

This method sets a color value of a pixel at given coordinates. The color must be an RGBA value encoded in a single long integer. You can use the MakeRGBA() convenience function in the helper library to encode color components.

int GetWidth()

This method returns the width of the subframe.

int GetHeight()

This method returns the height of the subframe.