CCReflect has a few interesting features that are quite desirable for DigiPen game projects:

Transcription

1 CCReflect v1.0 User Manual Contents Introduction... 2 Features... 2 Dependencies... 2 Compiler Dependencies... 2 Glossary... 2 Type Registration... 3 POD Registration... 3 Non-Pod Registration... 3 External Registration... 4 MetaData Instance... 4 Retrieving Type Information... 4 Serialization... 5 Deserialization... 5 Lua Function Registration... 6 Calling Member Functions from Lua... 6 Send Objects to Lua... 6 VariantFunction... 6 Calling a VariantFunction... 7 Binding a VariantFunction... 7 Run-Time Enumeration Editing... 7 LuaInterface... 7 Enumerations to Lua... 7 Lua Coroutines... 7 Setting an Object s Update as a Coroutine... 8 Zero Seconds Pause... 9 Threads Clocks and Timers... 9 Variant... 9 RefVariant... 9 Contact... 10

2 Introduction Reflection in C++ is a way of storing information available at compile-time. Usually, upon compilation, much information about the compiling code is lost. This information, if accessible during run-time, could be used for some desirable features. Features CCReflect has a few interesting features that are quite desirable for DigiPen game projects: Automated serialization of objects to a text file Automated registration of any C++ function to Lua Automated to Lua functionality for C++ objects Simple to implement generic messaging Generic functor object called VariantFunction o Bindable to object methods and object instances Run-time enumeration editor o Can add and remove C++ enumerations at run-time Enumerations to Lua and back Simple and easy to use Lua coroutine support o Great for running AI routines that can pause and resume Simple threading library with generic functor Threaded clock and timer Variant and RefVariant data type o Generic wrapper around any C++ type, for more generic programming Dependencies CCReflect comes with very little dependencies. Currently there are dependencies on: Lua; my own Containers Library; my own Utility Library. All three dependencies, along with source, are statically linked to the library. Overall CCReflect is self-contained. Compiler Dependencies Current CCReflect has only been compiled on Microsoft Visual Studio 2010 and Any other compiler versions will likely require minimal porting, but I myself will not do any porting. Glossary MetaData POD - Information about information. In general this means information stored by CCReflect about some sort of data type in C++. Also called meta data. - Plain old data type. No constructor, no heap memory. Just some bytes.

3 Type Registration In order for information about a specific type of data in C++ to be known to CCReflect, a small bit of registration code is required. The registration code is designed to look like simple C code. I have already registered most base types, and made a short list of types that come pre-registered with CCReflect: int float double bool char char * unsigned int int * void * std::string std::vector<int> std::vector<float> std::vector<double> std::vector<bool> std::vector<char> std::vector<unsigned int> std::vector<std:string> POD Registration Here is an example of registering some primitive types: NOTE: This macro is intended to be placed within a CPP file. This macro registers meta data information about a POD type. It is important to register POD types with the POD macro for optimization purposes. Non-Pod Registration Registering structures or classes that are not POD types is done like the following: NOTE: This macro is intended to be placed in a CPP file.

4 Registering a type with the DEFINE_META macro allows for reflection of private members. In order to support this feature a small META_DATA macro must be inserted into the public section of your type, like the following is placed within the Clock class: Once these two steps are performed, all initial registration is complete. External Registration To register a non-pod type to which you do not have source code access to the DEFINE_META_EXTERN macro is used: This macro does not allow private member access. MetaData Instance A meta data instance contains all the type information of a registered type, and provides access to interesting functionality. Serialization, to and from Lua, along with other useful methods are all packed into the MetaData class. The next section details how to access a particular MetaData object. Retrieving Type Information Retrieving the meta data of a type is a common task. There are three ways to retrieve this information. The first way is by explicitly saying what the type you re referring to is: The above code retrieves a pointer to the meta data for the type of integer. Another way to retrieve meta data is with an instance of an actual object. CCReflect uses decltype to deduce the type of an expression. Here is an example: The last way to retrieve meta information is by string, as shown here:

5 Serialization Any type can be serialized so long as it is registered within CCReflect. The syntax for serializing a type to a text file is as follows: In the above image o is just an object whose type has been registered within CCReflect. Note that the File class is used for serialization. The File class is my own utility class packaged with CCReflect, and it just a small wrapper around standard C file I/O. Here is a small example of an object serialized to stdout: Here is an example text file of the format for serializing a more complex object: The values are accurate: I was too lazy to set them :) Deserialization Similar to serialization, deserializing an object is done like so: Deserialized objects are returned via RefVariant. Please read the RefVariant section to find out more about the RefVariant. Deserialization of a file starts with the object at the top of the file. To deserialize the next object in the text file call Deserialize again and pass the same file to the Deserialize function. An empty RefVariant is returned if the entire text file has been read.

6 Lua Function Registration Registering a function to be used within Lua requires a single line of code: The REGISTER_FUNCTION macro is used. The first parameter of the REGISTER_FUNCTION macro is the name you wish to use for the function within Lua itself. The second parameter is the actual C++ function you wish to bind to Lua. Please note that binding member functions to Lua is not the same as binding a global function. Calling Member Functions from Lua In order to call a member function of an object from Lua, the first argument of the function call from Lua must be the this pointer. This is how Lua works. Here is an example: The above code uses the Lua colon syntax. The colon passes the cloud object itself as the first parameter to the bound C++ function called SetYVelocity. The actual call to C++ would have the cloud pointer be the first parameter, and 4 as the second. Send Objects to Lua Sending an object to Lua requires a single line of code, assuming the type of the object has been properly registered: In the above image o is the object itself, v is a RefVariant containing o, and L is the Lua state. Note: All objects sent to Lua are sent by a reference pointer! If you send stack memory to Lua it is your fault if that memory is reclaimed by the stack before the next time you access it. VariantFunction CCReflect offers a generic function pointer wrapper called the VariantFunction. The VariantFunction can wrap around any function in C++, and is called with the call operator ( ). This is very useful for setting up your own messaging system, or any other C++ construct that requires generic functor objects (like script binding). Here is an example of how to create a VariantFunction: In the above code the main function is bound. The first parameter is just a string to name the variant function. This is for internal usage, but can also be useful for debugging purposes. If you wish to not have any name just pass a NULL byte.

7 Calling a VariantFunction Any parameter can be passed to the VariantFunction upon call. Please note that the first parameter must be a RefVariant. This RefVariant will contain any return value from the VariantFunction s internal function pointer. The above example passes a temporary RefVariant, I suggest doing this if you know your VariantFunction does not have a return value. Binding a VariantFunction Binding a VariantFunction to a specific object in order to call member functions is done like so: The next time this VariantFunction is called, a this pointer referring to the object o will be used (assuming main is a valid member function of some class or struct). Run-Time Enumeration Editing CCReflect comes packaged with a run-time enumeration editor. Currently the editor is a WIP, but can live-edit C++ enumerations. LuaInterface Packaged within CCReflect comes a simple LuaInterface object. Only a single instance of the LuaInterface can exist. This interface provides access to all things Lua, such as creating your own coroutines, initializing Lua, loading Lua files, and calling functions within Lua. Please see LuaInterface.h for more details. Enumerations to Lua Enumerations can be freely sent to and from Lua. When sending an enumeration to Lua the enumeration is converted to a string. When sending an enumeration from Lua to C++, a much slower string comparison check is currently used to convert to an integral value. I suggest only sending enumerations to Lua from C++. Sending an enumeration to Lua is currently have an API re-write. Lua Coroutines One of the most attractive features of CCReflect is the usage of Lua coroutines. A coroutine in Lua is a function call that can be paused and resumed at will. The entire state of the function that had been called will be saved upon pause, and can be resumed to the previously paused state in perfect condition.

8 This allows for very simple and effective behavioral scripts to be written like so: As you can see, the WaitSeconds function is utilizing coroutine pausing in order to facilitate very readable and powerful script code. Setting an Object s Update as a Coroutine To setup an object s update function inside of Lua, a small LuaScript object needs to be placed within your object like so: When your object is constructed, you should initialize, in the object s constructor, the script like so: The line script.load will actually call the script that had been specified by the scriptname.c_str( ) portion. It is important to structure your coroutines such that the first few lines initialize your object followed by a pause, then a loop. A common setup for update functions with coroutines looks like the following: The first pause is important! This pause will pause your coroutine until it has been resumed. To resume a coroutine simply use this line of code in your object s update function:

9 You do not pass any parameters to resume. In GAM 200 and 250 every single object in our game had C++ update functions with one line of generic code, like above. The only thing that differed from object type to object type was the script s name in Lua. Zero Seconds Pause WaitSeconds performs floating point comparisons every time Resume is called, and will only un-pause the coroutine until that amount of time has passed. This can be unnecessary if you only want to wait for one game frame. Please use coroutine.yield to wait a single frame: Threads Clocks and Timers These are all newer additions to the CCReflect library, and this section will be written shortly. Variant The Variant type in CCReflect is an object that contains some heap memory. This heap memory is of a specific object type. In this way a Variant can contain any type of C++ type within itself. To retrieve the data from within a Variant, some internal typecasting is used. Here is an example: The above code creates a Variant of an integer that holds the value of 10 on the heap. The next line retrieves the internal data through pointer typecasting. RefVariant The RefVariant is the Variant s optimized counterpart. The RefVariant simply refers to another chunk of memory in C++ by pointer. In this sense a RefVariant is simply a generic reference to another object. This is ideal for many situations when the use of a heap-allocating Variant is not acceptable. Here is an example of creating and using a RefVariant: The above code snippet creates a RefVariant referring to the integer x. The next line of code then assigns the value of x to a new integer y.

10 In this way RefVariants are the perfect data type for implementing advanced type-safe and efficient messaging systems. RefVariants are the backbone of all Lua binding and VariantFunction functionality as well. Contact r.gaul at digipen.edu