<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" media="screen" href="/~d/styles/rss2full.xsl"?><?xml-stylesheet type="text/css" media="screen" href="http://feeds.feedburner.com/~d/styles/itemcontent.css"?><rss xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:wfw="http://wellformedweb.org/CommentAPI/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sy="http://purl.org/rss/1.0/modules/syndication/" xmlns:slash="http://purl.org/rss/1.0/modules/slash/" version="2.0">

<channel>
	<title>（╯°□°）╯︵ ┻━┻</title>
	
	<link>http://www.lavasandwich.org</link>
	<description>Geoff Evans, Game Developer</description>
	<lastBuildDate>Wed, 28 Sep 2011 00:27:55 +0000</lastBuildDate>
	<language>en</language>
	<sy:updatePeriod>hourly</sy:updatePeriod>
	<sy:updateFrequency>1</sy:updateFrequency>
	<generator>http://wordpress.org/?v=3.3.2</generator>
		<atom10:link xmlns:atom10="http://www.w3.org/2005/Atom" rel="self" type="application/rss+xml" href="http://feeds.feedburner.com/LavaSandwich" /><feedburner:info xmlns:feedburner="http://rssnamespace.org/feedburner/ext/1.0" uri="lavasandwich" /><atom10:link xmlns:atom10="http://www.w3.org/2005/Atom" rel="hub" href="http://pubsubhubbub.appspot.com/" /><item>
		<title>Some Code Organization Patterns</title>
		<link>http://www.lavasandwich.org/2011/06/01/some-code-organization-patterns/</link>
		<comments>http://www.lavasandwich.org/2011/06/01/some-code-organization-patterns/#comments</comments>
		<pubDate>Wed, 01 Jun 2011 07:00:22 +0000</pubDate>
		<dc:creator>geoff</dc:creator>
				<category><![CDATA[AltDevBlogADay]]></category>
		<category><![CDATA[best practices]]></category>
		<category><![CDATA[code organization]]></category>
		<category><![CDATA[patterns]]></category>

		<guid isPermaLink="false">http://www.lavasandwich.org/?p=219</guid>
		<description><![CDATA[This was originally published on AltDevBlogADay in June of 2011 Lately I am settling into a new job over at Neversoft.  There are some awesome folks over there, and I am really enjoying it so far.  Along with starting a &#8230; <a href="http://www.lavasandwich.org/2011/06/01/some-code-organization-patterns/">Continue reading <span class="meta-nav">&#8594;</span></a>]]></description>
			<content:encoded><![CDATA[<p><em>This was originally published on <a href="http://altdevblogaday.com">AltDevBlogADay</a> in June of 2011</em></p>
<p>Lately I am settling into a new job over at Neversoft.  There are some awesome folks over there, and I am really enjoying it so far.  Along with starting a new job comes learning a completely different codebase.  This can be especially arduous for tools folks since tools code typically sits atop a mountain of engine, pipeline, and foundation code.</p>
<p>In trying to wrap my head around an entirely new chunk of tech, I keep re-discovering patterns that make it easier to get your bearings on a lot of new code quickly.  There are lots of these patterns that studios follow when organizing their code, and following these can make it easier to dive and and start getting work done (or just make getting work done in general).  Some or all of these may be obvious to experienced engineers, but I figure it never hurts to reinforce best practices, and you never know when someone will have the total opposite opinion for really interesting reasons.</p>
<p><strong>Maintain just a handful of high level solutions so its easy to gain grand perspective.</strong></p>
<p>The lower the solution count in your project the better.  Ideally they should all be in the top level folder of your code.  The key here is to create awareness of the major chunks of technology in your project.  I think most people agree that the bar should be low for any engineer to get in and look at tools, engine, or game code.  The more you hide solutions within your code tree the more arcane knowledge is required to even know who the major players are in your codebase.</p>
<p><strong>Direct all compiler output to a single folder.</strong></p>
<p>Nothing hurts broad searches more than having large binary files mixed in with the source you are trying to search.  It&#8217;s probably the reason why Visual Studio has preconfigured laundry lists of source code file filters in their Find in Files tool.  If you redirect all your compiler output folders to its own root folder then broad searches gets orders of magnitude faster since it doesn&#8217;t have to wade through compiler data.</p>
<p>If your compiler output is directed to a separate dedicated folder then doing a clean build is just a simple matter of destroying the output folder and re-running your build.  Explicit cleans are just slower, and its just easier to delete a folder when scripting things like build server operations.</p>
<p>Code generated via custom build steps counts as compiler output too!  Add your output location an include path and #include generated code, even c/cpp files.  Doing this keeps a very clear distinction between generated code and code which belongs in revision control (and hopefully you aren&#8217;t storing generated code in revision control!).</p>
<p><strong>Keep 3rd party library code and solutions separate.</strong></p>
<p>A big part of effectively searching through your codebase is being able to differentiate your code from external library code.  Littering 3rd party libraries in with your own code can muddle search results.</p>
<p>Frequently its not necessary to clean build both 3rd party code and your project code, so having separate solutions can save time.  It also makes performing search and replaces within solutions that only have your project code in them safer (you don&#8217;t want to search and replace within a 3rd party lib do you!?).</p>
<p><strong>Install large 3rd party SDKs directly onto workstations.</strong></p>
<p><strong> </strong>Revision control isn&#8217;t the only software delivery mechanism on the planet.  Nobody should be making changes within the CellSDK, DirectX SDK, or FBX SDK so they shouldn&#8217;t be checked into revision control.  These packages tend to be very easy to script for unattended installation (msiexec).  This makes it easy to write a simple SDK checkup script to make sure that any given client (even build servers) have the latest kit installed.</p>
<p>Most large SDKs have environment variables that make them easy to find on the system, and even if they don&#8217;t you can typically assume where it should be installed.  If they are missing it&#8217;s a simple thing to track down and install t (even for junior or associate engineers).  Also, it never hurts to add compile asserts to validate that the code is being built against the correct version of those libraries.</p>
<p>If you happen to develop on a system with a package manager, they are awesome for making it easy to pull down 3rd party libraries directly off the internet.  Microsoft&#8217;s <a href="http://coapp.org/">CoApp</a> project aims to do just that on Windows.</p>
<p><strong>Only check in binaries of what you cannot easily compile.</strong></p>
<p>The less compiled binaries you check in the better your revision control will perform, and everyone you work with is served better when revision control works well.  Source code is much quicker to transfer and store on servers and peers.  Not checking in compiled binaries means less waiting for transfers, less locking for centralized servers, and less long term size creep for distributed repositories.</p>
<p>Checking in built versions of libraries will create a headache for yourself in the future when you want to deploy a new compiler or support a new architecture (which will require you to recompile using a bunch of crusty project files that haven&#8217;t been used in months or years).  It&#8217;s always worth a little extra time when adding a new external library to take command over your build configuration management.  Sometimes this can involve making your own project files instead of using ones that may be included with the library source code.  High level build scripting tools like Premake, CMake, and boost::build are worth spending time to learn, and can make hand-creating IDE-specific projects seem archaic.  If updating external libraries in your engine is easy you will do it more often, and hence reap the benefit of more frequent fixes and improvements you don&#8217;t have to do yourself.</p>
]]></content:encoded>
			<wfw:commentRss>http://www.lavasandwich.org/2011/06/01/some-code-organization-patterns/feed/</wfw:commentRss>
		<slash:comments>0</slash:comments>
		</item>
		<item>
		<title>PopStocks: Post-Mortem of a Facebook Game</title>
		<link>http://www.lavasandwich.org/2011/03/01/popstocks-post-mortem-of-a-facebook-game/</link>
		<comments>http://www.lavasandwich.org/2011/03/01/popstocks-post-mortem-of-a-facebook-game/#comments</comments>
		<pubDate>Tue, 01 Mar 2011 08:00:02 +0000</pubDate>
		<dc:creator>geoff</dc:creator>
				<category><![CDATA[AltDevBlogADay]]></category>
		<category><![CDATA[facebook]]></category>
		<category><![CDATA[google app engine]]></category>
		<category><![CDATA[post-mortem]]></category>

		<guid isPermaLink="false">http://www.lavasandwich.org/?p=210</guid>
		<description><![CDATA[This was originally published on AltDevBlogADay in March of 2011 Myself, Andy Burke, Rachel Mark, Marc Hernandez, and Paul Haile have built a Facebook game.  The goal was to spend 1 week building a game that would be fun enough and monetized &#8230; <a href="http://www.lavasandwich.org/2011/03/01/popstocks-post-mortem-of-a-facebook-game/">Continue reading <span class="meta-nav">&#8594;</span></a>]]></description>
			<content:encoded><![CDATA[<p><em>This was originally published on <a href="http://altdevblogaday.com">AltDevBlogADay</a> in March of 2011</em></p>
<p><a href="http://twitter.com/gorlak">Myself</a>, <a href="http://twitter.com/andybrk">Andy Burke</a>, <a href="http://twitter.com/kramdar">Rachel Mark</a>, <a href="http://twitter.com/marcsh">Marc Hernandez</a>, and <a href="http://twitter.com/Pacman2k">Paul Haile</a> have built a Facebook game.  The goal was to spend 1 week building a game that would be fun enough and monetized well enough to grow into something that could generate some actual income.  While we aren&#8217;t quite done with the game yet, I feel we have learned enough major lessons to justify a pre-launch Post-Mortem.</p>
<p><a href="http://www.facebook.com/apps/application.php?id=201641909847723"><img class="alignnone size-full wp-image-1829" src="http://lavasandwich.org/wp-content/uploads/2011/03/popstocks-logo-large.png" alt="" width="150" height="150" /></a></p>
<p><a href="http://www.facebook.com/apps/application.php?id=201641909847723"><strong>PopStocks</strong></a> models a stock market, but instead of companies we trade shares in Facebook Pages as items of value.  A Facebook Page must have at least 100,000 likes before we create a stock for it in our game, and the number of likes for that page dictates the total capitalization of the stock.  Every stock starts out at 25 Pops (our in-game currency), and its value on the market is dictated by market orders, limit orders, and rumors.  Rumors are actions that players can purchase with Facebook Credits, and can effect the market price of a stock.  PopStocks also has a store with power-ups that can prioritize a player&#8217;s trades, provide advice on what to trade, and offer more in-game currency in exchange for Facebook Credits.  We are currently in the process (this very weekend) of adding more items to the store that are for players that want to redeem in-game wealth for real-world discounts and items.  We aim to be feature complete by Monday and just focus on polish and marketing buys through Friday.</p>
<p><a href="http://lavasandwich.org/wp-content/uploads/2011/03/popstocks-excited-small.png"><img class="alignnone size-full wp-image-1827" src="http://altdevblogaday.com/wp-content/uploads/2011/03/excited-a-small.png" alt="" width="150" height="150" /></a></p>
<p><strong>What Went Right</strong></p>
<ul>
<li><strong>Shared vision of what we were building.</strong> We spent our entire first day working through what the social and monetary implications were for all our ideas.  PopStocks ended up being the idea with the lowest cost to implement, lowest amount of art required, and had the highest potential for monetization.  The idea of a virtual stock market wasn&#8217;t really new, but the idea of using Facebook itself as the source for stocks gave the entire team ideas about where to take our game.</li>
<li><strong>Google App Engine as a development platform.</strong> Python and Google&#8217;s data model classes (backed by BigTable) made fleshing out new functionality a breeze.  While the BigTable backend does have limitations with what is possible with its query construction, the fact that you can rearrange your data so quickly makes it an all around win.  Google has made specific choices about what features are available in queries for performance and scalability reasons, and deciding to prohibit inefficient features causes your design to iterate toward something that is more optimal than if you had every feature of SQL.  While Eclipse as an IDE and debugger leaves a lot to be desired (it suffers every trap of software too focused on plug-ins than unified workflow), its totally passible for a short project like PopStocks.  Deployment to Google&#8217;s servers is a breeze, and the backend control panel has just about every feature you could need.</li>
<li><strong>99 designs as a marketplace for art and iconography.</strong> From the get-go we wanted a game that was as minimal on art as we could get.  We are all engineers, and didn&#8217;t have the cash on hand to put a lot of money into art.  We used <a href="http://99designs.com/">99designs.com</a> for only the important items we absolutely needed: a logo, a trophy icon, and some images of our broker character in various emotional states.  We put up a 3 day contest and didn&#8217;t see much we liked until the very last day where we got a submission that just hit out-of-the-park what we were looking for.  For only a couple hundred dollars we had enough art to get to alpha.</li>
<li><strong>Every developer uses a different platform and browser.</strong> The entire team had coverage of Mac, Linux, and Windows, and used Chrome, Firefox, IE, and Safari to develop features with.  This brought to light compatibility issues extremely quickly, and in general we were running in every browser all the time.  Despite Eclipse&#8217;s usability drawbacks, it has functioned very well on all our development platforms.  We spent one day getting all our workstations configured as a full development environment and it hasn&#8217;t been a time sink since.</li>
<li><strong>Multiple builds of the game in Facebook. </strong>We setup 3 actual applications in Facebook: PopStocks-devel which points to localhost/127.0.0.1 (we run a local Google App Engine SDK server instance so we can debug the Python), PopStocks Playground which runs on Google App Engine but has debug features enabled, and the final game application: PopStocks.  Having Playground as an application in Facebook was invaluable for doing quick test passes before deploying to production.  We could also completely burn the data store on playground after hacking it up for various development reasons.  We did our initial testing with our friends on Playground before we were comfortable enough to launch the main game.  We didn&#8217;t want to ever have to wipe the data store for the production instance.</li>
<li><strong>Git and GitHub.</strong> Git is fantastic and GitHub makes it even better.  We worked exclusively through a GitHub private repo, which is only $25/mo.  We used its simple (but good enough) ticketing system for our issues as well as user-contributed bugs (contributed via a submission form in the game).  GitHub was only down for 30 minutes in the middle of one of the nights we were working.</li>
</ul>
<p><a href="http://lavasandwich.org/wp-content/uploads/2011/03/popstocks-disappointed-small.png"><img class="alignnone size-full wp-image-1828" src="http://altdevblogaday.com/wp-content/uploads/2011/03/dissapoint-small.png" alt="" width="150" height="150" /></a></p>
<p><strong>What Went Wrong</strong></p>
<ul>
<li><strong>Learning to program for the web.</strong> Everyone on the team had varying degrees of experience with developing for the web.  Andy had the most experience (with Google App Engine, Python REST APIs, and Javascript), and probably spent half of his time just talking through with the rest of the team how things should work, and pointing out which mistakes were worth correcting and which were not.  Time being a valuable commodity it is important to decide when to undertake refactoring passes (or when to burn entire features).  Keeping the game running is important sometimes, but not others.  We ended up building most of our features before doing any significant refactoring and then doing one massive reorganization to correct past mistakes several days before launch (last night).</li>
<li><strong>Facebook authentication.</strong> To authenticate as a user logged into Facebook one must parse a &#8216;signed_request&#8217; which is delivered in a POST on initial page load.  Being one of the first things your game would need to do, you would think there would be some handy example code in the official Facebook Python SDK.  Yeah, not so much.  Lacking good (or obtainable) documentation about what exactly a &#8216;signed_request&#8217; is and how to parse one, it took quite a bit of digging to get it working.  Turns out there is a pending pull request to add the necessary code to the official Facebook Python SDK, but nobody at Facebook has accepted that request yet.  This burned about half a day&#8230; for something that should be documented as step 1 for building a Facebook application.</li>
<li><strong>Facebook stability issues.</strong> Sometimes Facebook will take its sweet time to reply to graph API requests&#8230; and sometimes it&#8217;s graph API code will timeout because the site just takes too long to reply.  Sometimes certain searches will break and fix themselves during the day.  We haven&#8217;t found much visibility into how to monitor these stability gaps, you just have to take them in stride.  Also, if you use FQL, make sure not to use LIMIT 1 in your queries because sometimes it will just give you zero results instead of the first item you were searching for.</li>
<li><strong>Internet Explorer being what it is.</strong> <a href="http://bits.blogs.nytimes.com/2010/09/17/a-loophole-big-enough-for-a-cookie-to-fit-through/">CP=HONK</a> is the magic that is needed to make iframe cookies work in IE.  Also, don&#8217;t forget to omit the final comma delimiter in JavaScript lists.  Also, setTimeout().  We had to make more exceptions for IE than any other browser, by far.  Supporting IE 8 cost our project at least 1 man day.</li>
<li><strong>GDC.</strong> The Game Developer&#8217;s Conference happened right in the middle of our production period, but there wasn&#8217;t anything we could do about that.  We lost more than half the team for an entire week which put a ton of work (and crunch) on a very few.  It also took attendees some time to hit the ground running after focusing on other things at GDC for an entire week.</li>
</ul>
<p><a href="http://lavasandwich.org/wp-content/uploads/2011/03/popstocks-happy-small.png"><img class="alignnone size-full wp-image-1841" src="http://altdevblogaday.com/wp-content/uploads/2011/03/happy-small.png" alt="" width="150" height="150" /></a></p>
<p><strong>Conclusion</strong></p>
<p>Everything took longer than we thought it would, and we ended up tripling our 1 week deadline.  Feature creep contributed about a week to our blown deadline.  Halfway into the first week we saw that things were taking a long time to come online, and we started to worry that we wouldn&#8217;t have enough compelling gameplay to be viable to even our friends (much less complete strangers).  If we had stuck to our original plan of a very minimal feature set we might have completed our game in two weeks, but it wouldn&#8217;t be nearly what it is today.  Lets hope that bet pays off.</p>
]]></content:encoded>
			<wfw:commentRss>http://www.lavasandwich.org/2011/03/01/popstocks-post-mortem-of-a-facebook-game/feed/</wfw:commentRss>
		<slash:comments>0</slash:comments>
		</item>
		<item>
		<title>Behind the Mirror</title>
		<link>http://www.lavasandwich.org/2011/02/01/behind-the-mirror/</link>
		<comments>http://www.lavasandwich.org/2011/02/01/behind-the-mirror/#comments</comments>
		<pubDate>Tue, 01 Feb 2011 08:00:56 +0000</pubDate>
		<dc:creator>geoff</dc:creator>
				<category><![CDATA[Game Developer Magazine]]></category>
		<category><![CDATA[c++]]></category>
		<category><![CDATA[programming]]></category>

		<guid isPermaLink="false">http://www.lavasandwich.org/?p=185</guid>
		<description><![CDATA[Reflection is a programming language feature that adds the ability for a program to utilize its own structure to inform its behavior. Reflection has its costs, but those are often outweighed by ability to automate the following:
• Serializing objects into and out of a file
• Cloning, comparison, search indexing, and network replication
• Type conversion (copying base data between derived class instances)
• User interface generation and data binding <a href="http://www.lavasandwich.org/2011/02/01/behind-the-mirror/">Continue reading <span class="meta-nav">&#8594;</span></a>]]></description>
			<content:encoded><![CDATA[<p><em>This article was originally printed as a <a href="http://gdmag.com">Game Developer Magazine</a> article in the February 2011 issue. It&#8217;s also available online at <a href="http://www.gamasutra.com/view/feature/6379/sponsored_feature_behind_the_.php">Gamautra</a> as a sponsored feature thanks to my ex-Insomniac friend and coworker Orion Granatir, who also moved on to <a href="http://intel.com">Intel</a>.</em></p>
<p><strong>Adding Reflection to C++</strong></p>
<p>Reflection is a programming language feature that adds the ability for a program to utilize its own structure to inform its behavior. Reflection has its costs, but those are often outweighed by ability to automate the following:<br />
• Serializing objects into and out of a file<br />
• Cloning, comparison, search indexing, and network replication<br />
• Type conversion (copying base data between derived class instances)<br />
• User interface generation and data binding</p>
<p>Of course all of these tasks can be accomplished without reflection capabilities, but you will likely pay higher costs having to write code that is very rote and prone to error. A good implementation of reflection can provide a platform on which each of these problems can be solved without glue code in every class that desires these features.</p>
<p>At the highest level reflection can encompass many different features:<br />
• Runtime knowledge of class members (fields and methods)<br />
• Dynamic generation and adaptation of code<br />
• Dynamic dispatch of procedure calls<br />
• Dynamic type creation</p>
<p>However, for the purposes of this article I will define C++ Reflection to mean: having access at runtime to information about the C++ classes in your program.</p>
<p><strong>RTTI</strong></p>
<p>Before diving headlong into how to add reflection to C++, it’s worth noting what type information is already built-in. The C++ language specification provides minimal information about the classes compiled into a program. When enabled, C++ Run Time Type Information (RTTI) can provide only enough information to generate an id and name (the typeid operator), and handle identifying an instance’s class given any type of compatible pointer (dynamic_cast<>).</p>
<p>For the purpose of game programming, RTTI is often disabled entirely. This is because its implementation is more costly than a system built on top of C++. Even if a program only makes a handful of RTTI queries, the toolchain is typically forced to generate, link, and allocate memory at runtime for information about every class in the application (that has a vtable). This significantly increases the amount of memory required to load your program, leaving less memory available for face-melting graphics, physics, and AI. It&#8217;s better to implement your own RTTI-like system that only adds cost to the classes that need to utilize it. There are plenty of practical situations where vtables make sense without needing to do runtime type checking.</p>
<p>Thus, the first step in implementation of a reflection system is typically a user implementation of RTTI features. This can be accomplished with only a couple of steps.<br />
Type information can be associated by a static member pointer (which also makes a good unique identifier for any given type within the program). In addition, some virtual functions allow querying an object&#8217;s exact type, as well as test for base class types:</p>
<pre>
// Returns the type for this instance
virtual const Type* GetType() const;

// Deduces type membership for this instance
￼virtual bool HasType( const Type* type ) const;
</pre>
<p>GetType returns a pointer to the static type data, and HasType compares the provided type against its static type pointer as well as every base class&#8217; type pointer. This gives us all the information needed to re-implement dynamic_cast<>, but it only adds overhead to classes that are worth paying the added cost of type identification and type checking.</p>
<p><strong>Visitor Pattern</strong></p>
<p>The simplest technique for implementing reflection is to take a purely programmatic approach. Virtual functions can be a mechanism for the traversal of all fields in a class.<br />
The visitor design pattern provides an abstraction for performing arbitrary operations on the fields:</p>
<pre>
// a base class for any object that
//  wants to reflect upon any class' fields
class ObjectVisitor
{
public:
    virtual void VisitField( int32_t&#038;, const char* ) = 0;
};

// an example of a class that would write/read
//  from/to each field to/from a file
class SerializeVisitor : public Visitor
{
public:
    virtual void VisitField( int32_t&#038; value, const char* name )
    {
        // do serialization work
    }
};

// a base class for some of your reflection-aware objects
class Object
{
public:
    virtual void Accept( ObjectVisitor&#038; visitor ) = 0;
};

// an example of a derived class that has a reflected field
class Foo : public Object
{
public:
    virtual void Accept( ObjectVisitor&#038; visitor )
    {
        visitor.VisitField( m_Number, "Number" );
    }

private:
    int32_t m_Number;
￼};
</pre>
<p>This is a textbook implementation of the visitor design pattern. Objects deliver the visitor to each one of its fields and the visitor gets an opportunity to transact with each field in series. It offers excellent encapsulation since the object does not know or care about any implementation details of what the visitor is trying to accomplish.</p>
<p>This technique does not require data from an external tool to do its job since it’s implemented entirely in the code compiled into the program. It’s simple to step through and debug, and extensible since many operations can be implemented as another class of Visitor.</p>
<p>With this approach, the development cost is small. A single line of code for each field in every class in your codebase is a fair price to pay to attain the benefits reflection can provide. However, there are some drawbacks with using a visitor function for reflecting upon your objects. There are a lot of virtual function calls happening to interact with each field in a class. This is a concern for performance critical code and on certain platforms. Also, this technique is best suited for operations that want to visit every single field of a class. There are many situations where this work is not required, and iterating over every field just to access a few is wasteful and time consuming (depending on the size of the object).</p>
<p><strong>Data Model</strong></p>
<p>To really take reflection to the next level it&#8217;s necessary to be able to address specific fields and read and write data without iterating over every field in the class. A data model that represents the classes and fields specified in the code is needed to accomplish this. At runtime your program can reflect upon this model to interface with objects and their field data.</p>
<p>This data model is owned by a central registry of type information. This singleton object owns all the type information in the program and can have support for finding type information by name. It&#8217;s also a central point where a map of the entire inheritance hierarchy of classes can be built. The registry can be populated by employing a parser tool to analyze your source code, or by adopting a method similar to the visitor function approach to populate this data model at program startup.</p>
<p><strong>To Parse or Not To Parse&#8230;</strong></p>
<p>Using a parsing tool to analyze your code introduces a lot of complexity. C++ has a very complex syntax. While there are some tools you can take off the shelf to do the parsing, there is still a lot of work to do to make that data usable at runtime. Typically, you want to extract just the necessary data from the abstract parse tree and write out a meaningful representation of only the data that is required for what you want to reflect upon.  Templates, typedefs, functions and other language features are generally overkill for the purpose of reflecting upon fields in a class.</p>
<p>A parsing tool is probably going to do one of two things: write a data file to be loaded at runtime (or packed into the executable as a global variable or resource section), or it&#8217;s going to generate some code that gets compiled into your program.</p>
<p>If you choose the data file route, you have the added task of computing member size and offset information. This information is compiler specific and target platform specific. By<br />
choosing this approach you are committing to abide by the padding and alignment rules of whatever compiler you use to build any given version of your program. Another source of complexity comes from the existence of two independent pipelines processing information about your code: the compiler and the parsing tool. This necessitates synchronizing the data output by the tool with the specific version of the compiled program, which will make packaging and deploying your program harder. Synchronization is a very important problem to solve in this approach because not detecting out of sync reflection information can cause nasty bugs (and potentially mangled data).</p>
<p>If you choose to generate source code to be compiled into your program, you inherit the burden of the complexities that come with creating a code generator that is most likely specific to your particular needs. The code generation tool will probably need to make a bunch of decisions about how your code needs to be decorated and organized. These requirements will change as your codebase evolves, and it will require you to be diligent about releasing and configuring your own build tool. Also, maintaining a tool that governs the ability to compile your game is risky because it has a tendency to break at the worst possible time (during a milestone).</p>
<p>The reward for using these approaches is tangible. You don’t have any code that needs to be written by hand to reflect upon your classes. If you choose to generate code, then you will also probably get great performance since you can generate function bodies that do specific operations on every field of your classes, just like you would have done if you weren’t using reflection at all.</p>
<p>In reality, there are a ton of moving parts when using this approach. Things can break in hard to trace ways if any step of the pipeline doesn’t work as expected. Having implemented and maintained this technique for many years, I can tell you that there are days when it feels like the planets have to align for all the parts in this complex pipeline to actually work together in harmony.</p>
<p><strong>Hand Coding</strong></p>
<p>Alternatively, code can be written to populate the reflection data model when our program starts up. This code creates class information structures, populates them with information about every field within the class, and adds them to the registry. Writing this code sounds arduous, but C++ template support provides some excellent tools to accomplish this with remarkably concise and manageable code. A good goal for this is to extract as much information as possible in a single function call per field, per class (just like our visitor function). This allows us to avoid any time spent at build time processing source, managing dependencies on build tools, dependency checking generated code, and synchronizing externally loaded data.</p>
<p><strong>Polymorphic Data</strong></p>
<p>Because containers in C++ are template types instead of concrete types, function overloading can only take us so far. Since each template instantiation is a completely different type, trying to support containers using a visitor pattern could lead to a combinatorial explosion in the number of overridden functions. Enumerated data types present the same challenges. It&#8217;s not easy to support them via overloading since every enum in the entire game would need a different overload.</p>
<p>A solution to this shortcoming is to delegate the handling of any piece of data to a separate class of object that can interface with individual fields using a pointer. This will give us the ability to operate on any data in a polymorphic manner, including integer, floating point, and enumerated data types. Many languages that require derivation from a canonical Object class do this already. Adding support for treating simple types with polymorphism doesn&#8217;t mean that it&#8217;s necessary to use these polymorphic versions of these types everywhere in your code. They will only be used to abstract away the implementation details of dealing with serializing, comparing, and converting data to and from human readable strings (which is very handy for generating property UIs).</p>
<p>Truly polymorphic data can solve many edge cases and provide extensibility for user types like enums and exotic containers. It can also support user data types that need custom processing during serialization. If these data classes store a value in addition to working through a pointer, they can be used to interface with fields and store standalone data. This allows for interoperability between versions of the program that have slightly different fields without discarding this &#8220;unknown&#8221; information. This is a major coup for game development tools that revise sets of properties frequently between releases. You can publish a test release with a very different set of properties and know that if content creators check in some of those files they probably won&#8217;t break folks still using the stable production tools (since the stable tools data is still there in the files).</p>
<p>Every field in the reflection information will specify a class of object that will handle the details of reading and writing the necessary data to a persistence interface or other objects of the same type. With this in mind, it&#8217;s time to declare some data structures to store Class and Field information:</p>
<p><strong>Class</strong></p>
<p>Class stores all of the information for a class of object in your code (client object or data object):</p>
<pre>
struct Class
{
    const Class*            m_Base;     // our base class
    Array< const Class* >   m_Derived;  // our derived classes
    const char*             m_Name;     // our name (user-friendly)
    Array< const Field* >   m_Fields;   // fields of this class
    Class( const char* name )
        : m_Base( NULL )
        , m_Name( name )
    {
    }
};
</pre>
<p><strong>Field</strong></p>
<p>Field stores information about a particular member variable in a class. Fields are stored in an array in the Class object that owns them.</p>
<pre>
struct Field
{
    const Class*      m_OwnerClass;  // the class this is within
￼    const Class*      m_DataClass;   // the class of data
                                     //  that serializes the field
    const char*       m_Name;        // name of the field
    size_t            m_Size;        // the size of the field
    uintptr_t         m_Offset;      // the offset to the field

    Field( const Class* owner, const Class* data,
           const char* name, size_t size, uintptr_t offset )
        : m_OwnerClass( owner )
        , m_DataClass( data )
        , m_Name( name )
        , m_Size( size )
        , m_Offset( offset )
    {
    }
};
</pre>
<p><strong>Populating the Data Model</strong></p>
<p>To help populate the data model, some template functions can help extract useful data via template parameters:</p>
<pre>
template< class ObjectT, class DataT >
Field* AddField( Class* owner, DataT T::* field, const char* name,
                 const Class* data = NULL )
{
    // call out to a template function that is specialized
    //  to return the appropriate data class for this type of field
    // also compute the offset from the base pointer
    //  using the pointer to the member variable
    Field* field;
    field = new Field( owner,
                       data ? data : DeduceDataClass< DataT >(),
                       name,
                       sizeof( DataT ),
                       GetFieldOffset( field ) );
    owner->m_Fields.Push( field );
    return field;
}
</pre>
<p>A template function with parameters for the object type and variable type provides an easy way to extract the size of the variable, its offset from the base instance pointer (using a pointer to member variable), and it supports the use of template specialization to deduce which type of data object is applicable to this field. Three important things are happening in this function to extract data for our reflection data model: pointer to member variable C++ syntax, translation of this syntax into an offset from a base object address, and the use of deduction using explicit specialization.</p>
<p><strong>Pointer to Member Variables</strong></p>
<p>Pointers to member variables are a pretty infrequently used aspect of C++. It does what you might expect, but its syntax is strange if you haven&#8217;t seen it before:<br />
int32_t Object::* pointer_to_member_variable = &#038;Object::m_Member;<br />
￼These are typically dereferenced with an instance of the object type (just like member function pointers):</p>
<pre>
Object object, *pointer = new Object;
int32_t value1 = object.*pointer_to_member_variable;
int32_t value2 = pointer->*pointer_to_member_variable;
</pre>
<p><strong>Translation Into Offset</strong></p>
<p>To compute the offset from a pointer to a member variable:</p>
<pre>
template< class ObjectT, class DataT >
uint32_t GetFieldOffset( ObjectT DataT::* field )
{
    // a pointer-to-member is really just an
    //  offset value disguised by the compiler
    return (uint32_t) (uintptr_t) &#038;( ((ObjectT*)NULL)->*field );
}
</pre>
<p>This function doesn&#8217;t bother with allocating an instance to dereference the pointer to member variable. It substitutes a NULL pointer, dereferences the pointer to member variable, and uses the address operator to yield the offset (from NULL) at which the pointed member exists. Some of this syntax may seem strange if you haven&#8217;t used it before; but it&#8217;s a perfect fit for maximizing what information is needed to describe a field in a single function parameter.</p>
<p><strong>Explicit Specialization</strong></p>
<p>DeduceDataClass is a good example of template deduction using explicit template specialization. This deduction technique is a way of using the C++ template mechanism to allow for the automatic selection of some information by the template compiler based only on a template parameter. The default template function&#8217;s implementation returns NULL, indicating that the deduction failed since no specialization was found to find the associated data:</p>
<pre>
template< class DataT >
Class* DeduceDataClass()
{
    // unknown data!
    return NULL;
}
</pre>
<p>Then create an explicit specialization for every type that can be deduced:</p>
<pre>
template<>
Class* DeduceDataClass<uint32_t>()
{
    // this specialization associates the uint32_t
    //  built in type with an object class that can
￼    //  process data of type uint32_t with respect
    //  to other persistence / cloning / mining code
    return SimpleData< uint32_t >::s_Class;
}
</pre>
<p>In this case, a pointer is returned to the class reflection information for the type of data object to be used when dealing with the built-in type passed into the template argument.</p>
<p><strong>Putting It All Together</strong></p>
<p>One more template will help keep the code that registers classes at startup concise:</p>
<pre>
template< class ObjectT >
static Class* CreateClass( const char* name )
{
    Class* result = new Class( name );

    // populate the field information for this class
    ObjectT::Populate( *result );

    return result;
}
</pre>
<p>Finally, an example class and main that will put all of this code to work:</p>
<pre>
class Foo
{
private:
    uint32_t m_Number;
public:
    static Populate( Class&#038; c )
    {
        // AddField is a template function that will deduce
        //  everything but what the desired name is.
        Field* f = c.AddField( &#038;Object::m_Number, "Number" );
        // Its easy to imagine Field having extra information
        //  to inform all sorts of program behavior
        //  f->SetRange( 0, 10 );
        //  f->SetCategory( "Advanced Settings" );
    }
};

void main()
{
    Registry::RegisterClass( CreateClass< Foo >( "Foo" ) );

    // program goes here

￼    Registry::UnregisterClass( Registry::GetClass< Foo >() );
}
</pre>
<p><strong>Conclusion</strong></p>
<p>Reflection can imbue an enormous amount of flexibility to your game engine, but this flexibility doesn&#8217;t come without cost. However, the extra memory reflection data consumes is balanced by the time saved implementing features more rapidly. The ability to deliver changes to your users quickly, and with minimal engineering overhead will pay dividends as your user base grows and your production time stretches across multiple titles.</p>
<p><strong>Open Source Implementation</strong></p>
<p>Helium is an open source game engine toolkit that contains an implementation of C++ Reflection. Much of the code in this article was derived from it. It uses a BSD-style license, and is available at <a href="http://heliumproject.org">heliumproject.org</a>. The reflection system itself is located in the Foundation/Reflect folder within the source repository.</p>
<p><strong>Bio</strong></p>
<p>At the time of this writing, Geoff Evans was a Senior Engineer at WhiteMoon Dreams, Inc. in Los Angeles, CA. He was a founder of the Nocturnal Initiative open source project at Insomniac Games, and is a founder of the Helium Project (started at Whitemoon Dreams), which aims to build an open source commercial quality game engine.<br />
￼</p>
]]></content:encoded>
			<wfw:commentRss>http://www.lavasandwich.org/2011/02/01/behind-the-mirror/feed/</wfw:commentRss>
		<slash:comments>0</slash:comments>
		</item>
	</channel>
</rss>

