Reveal

Contents

Main | The page you're look at right now.
Integration | Explains how to hook Reveal into your application You can skip this if somebody on your team already integrated Reveal in your application.
Tutorial | Explains how to expose your variables, callbacks, etc. Read this if you want to expose some part in your game, and you have never used Reveal before. Note that the tutorial contains information on certain rationales as well.

FAQ

Contains some frequently asked questions

Advanced Use Explains some advanced additional Reveal features
Implementation

Contains some notes on the implementation
For people who need to change things in the implementation, or just a general interest in what kind of crappy coder I am.

Reveal Reference Doxygen reference for the Reveal namespace
Reveal::Callback Reference

Doxygen reference for the Reveal::Callback namespace

Reveal::SmartPtr Reference

Doxygen reference for the Reveal::SmartPtr namespace

Reveal::TypeTraits Reference

Doxygen reference for the Reveal::TypeTraits namespace

History

"Wouldn't be cool, if we could hook a mouse up to a console, and click on things and play around?"

Rudy Poat, November 2002

Reveal is a lightweight, easy to use, yet extremely powerful tweaker system that evolved from the above remark by Rudy Poat. I was planning on integrating some existing EA technology (Merlin, in fact) that relied on RealComm to communicate between a host-pc and a console. I figured it might be useful to get some experience with RealComm to cope with future problems, so I tried sending some mouse coordinates from a PC to a console. After drawing a rectangle at that position, and thus actually using the PC-mouse to control something on a console, the idea to extend it came from Rudy Poat and Brian Keane. The rest is history...

The FIFA team uses Reveal as a replacement for their previous debug menu. To give you an indication of what it looks like and what it can do, here are some screenshots with comments, taken from the FIFA PC build:

[Note as of March 19 2003: These screenshots are very outdated, and the look and feel GUI has improved a lot since. Soon this documentation will be updated to reflect the new GUI and some other new but still undocumented Reveal features (graphs, diagrams, firing auxilliary callbacks, and most of all, context-sensitive menus and picking)]

Obivously the GUI dissapears if you click anywhere outside of the menu.

Here I just clicked the transition-fire button. The transition-type control says "boxturn", and hence the boxed transition.

Notice the big fat pause button in the lower right corner. Ideal for taking screenshots. You can simply click on pause, click outside the GUI to remove the screen, and take your screenshot. Or use one of the auxillary buttons on the bottom bar to implement a 'screenshot' button, which is trivial to do.

FIFA, instead of hooking the pause button to a pause-callback, hooks the pause button into the replay system. If the pause button is pressed replay mode is enabled, and no frames are played. You can then use a slider-bar (range-control) to scroll through the past frames. This, combined with the free camera look, gives you anything you need to make screenshots of any action, from any angle, at any time so you're never too late with the screenshot button.

Features

Here's a list of some features that Reveal offers:

- Checkboxes
- Buttons
- Watches
- Color-pickers
- Option-controls
- Range-controls
- A Microsoft Windows start-menu-ish tree structure of exposed variables
- Most-Recently-Used menus (MRU's) that store the last few controls you have used
- Mouse-, keyboard- and pad-control, even on consoles. Note, a mouse and keyboard is not required, the console-pad works fine too.
- Easy to integrate
- Flexible callback mechanism
- No dependencies (zero, zilch, nada, njente)

Advanced features:

- Auxillary buttons (implement your own new functionality)
- Graphs (for functions, stastistics and diagrams)
- Context sensitive menus (right click on a player, ball, monster, enemy, whatever and have context sensitive menu pop up)
- Drag entities around in your world.

Requirements

Before I started coding, I had a few ideas about what I wanted the library to end up like. These can be summarized as follows.

- Any programmer, in any team, at any studio, should be able to integrate Reveal into an application in a very short time.
  It some technology is not easy to integrate, people will shy away from it because they can do a quicker job using some other library or tool. To qualify the above statement; if the Reveal client application is able to provide four basic 2D drawing routines (line, text, triangle, rectangle), and is willing to use either the provided RealComm or Win32 implementations of the input system, the time in between reading this for the first time, exposing your first variable, compiling, linking, running, and tweaking it on a single console should be no more than 90 minutes.
  In case you want to use your own inputsystem instead of the default Win32 or RealComm implementations, you have to provide a small wrapper yourself, which will probably add around 60 minutes, from reading about it to compiling and linking.
  Getting it to work on all platforms should theoretically take no time since it's all platform independent. However, taking Murphy's Law in account, add another 90 minutes.
- Preferably, there should be no dependencies on any other library, not even EA libraries.
  This is a consequence of the first requirement. Most existing EA library aren't lightweight enough to satisfy the first requirement if a dependency would be introduced. Therefore a wall is build between Reveal and the application which can be penetraded by lightweight wrapper classes.
  There are default implementations for the input wrappers that rely on either Win32 or RealComm for those who want to use them, but the Reveal system does not rely on any external libraries.
- Exposing any tweaker variable should be as easy as possible
  A library can be easy to integrate, but if its usage is very complicated people still won't use it. The goal of the Reveal library is to be able to tweak or watch certain variables and expose them in an easy to use way. Therefore, exposing a variable or whatever should be as easy and flexible as possible. To qualify the above statement, exposing a variable should take no more than one line of code, whether this variable is a float, integers, color or boolean. In fact, it shouldn't even matter if the variable is a member or a global. Also, it should also be possible to use callbacks intead of exposing variables directly. Also, it shouldn't matter if these callbacks are free functions, functors or member functions. One line of code should be enough.

Caveats

As opposed to the requirements, there are also some issues I want to avoid.

- Reveal should not implement a powerful GUI system
  I made the decision to avoid dependencies. Considering Reveal is a development tool we can get away with an ugly GUI that simply gets the job done. Therefore, I implemented a semi-ugly hardcoded GUI system that relies on four user supplied functions (line, triangle, text, rectangle). it is far from the most elegant way to implement a GUI but it works ok for our purposes.
  The hard part is to knowing when to stop. Something ugly and hardcoded works best as long as it is small, simple and has a limited scope. But it's all too easy to request more and more features of a GUI feature ("can you do drag and drop?", "can you do drop-down-boxes?", "can you do textfields?", etc. etc.) and before you know it, the ugly and hardcoded thingy grows into a gigantic monster that is hard to maintain and bug-ridden.
  Therefore, Reveal GUI proposals should be looked at on a case by case basis, and we should strive for some minimalism. If things get out of hand, and some quality GUI library pops up (the new Apt perhaps?) we should not be afraid to use it instead, in the future. Client code will never notice anyway.

Other Systems
For an overview of existing tweaker systems, check out the the sportscore tweaker discussion. I can especially recommend the system paper on tuners written by Jeremy Walker and John Harvey for EA Journal which never got published.

There are a few differences between Reveal and other tweaker systems. The ones worth mentioning are:

- Reveal is easy to integrate. Although I must admit that I have no experience with integrating the other tweaker systems, I think that Reveal is about as lightweight as possible.
- Reveal has the interface on the host-machine, instead of on the PC.
  This has both advantages and disadvantages. The major advantage is that we don't lose type-safety because of communication with a PC. Instead we have the full type information on the host-machine and that's where we can tweak things. A minor advantage is that the mouse pointer is actually on the screen meaning that it's easy and intuitive to control (where you look is what you control). The NHL 2001-in-game-tuner too had the interface on the host-machine.
  The major disadvantage of having the interface on the host-machine, instead of on the PC is that the GUI will suffer. If the actual tweaking would happen on the PC instead, the full Win32 API can be used, and hence really cool menus can be made. This is the approach that DeciTuner took as well, resulting in very easy-to-use interfaces.
- Reveal has a very flexible callback mechanism.
  This means that people can use references, functions, functors and member-functions as callbacks. Especially the last one is in these OOP days very handy. Without this, people would have to resort to hacks involving static-functions, storing this pointers, etc.
- Reveal is very flexible about the types it exposes.
  Reveal is not limited to just a few basic types like strings, floats and integers. Option controls and range controls can take any type you want. Especially for the option control this is a handy feature when an enumeration does not consists of an actual C-style enum, but, for example, an array of objects.
- I'm not sure about the other systems (maybe they do this as well), but Reveal runs on all four platforms, meaning PC, XBox, PS2 and Nintendo GameCube. Heck, it could run on a GBA if you would want to.

What's in the package

The following tables describe what is in the package.

reveal/ | Empty root of the package.
reveal/include | Directory contains all header files provided by the library.
reveal/lib | Directory contains all libraries available (PC, Xbox, NGC and PS2).
reveal/docs/ | Contains all documentation. Open the index.html file in there to get all you want.
reveal/bin/ | Contains the reveal_test_d application, which is a testbed for Reveal and demo of the gui.
reveal/source/lib | Contains all sources used by the libraries available to the clients.
reveal/source/test/ | Contains sources used by the reveal_test project.