Lesson 04 - Creating A Game World With Static Objects

 *//* 

This lesson will show you how to create and populate the world in which games are set. This lesson will only introduce static (as in unmoving) game objects and the structure thereof, as well as the structure of the classes which make up the game world.

• This lesson's source code
• Main lesson index

This game engine provides a set of classes to facilitate creation of interactive 2D game worlds. The intention is to provide only common functionality in these base classes (which will grow to include semi-game-specific functionality if/when it proves to be common to most game implementations), and leave game-specific details up to each game's implementation. The important classes are:

• Xrb::Engine2::World is what contains everything and is the main point of control for non-rendering game logic. Games may subclass it to provide game flow logic such as enemy spawning or victory condition detection. World contains multiple instances of ObjectLayer, all instances of Entity, and optionally an instance of PhysicsHandler.
• Xrb::Engine2::ObjectLayer contains all instances of Object. Depending on how the game world is rendered, ObjectLayer can be used to represent different depths in a view-parallaxed scene (i.e. foreground, midground and background layers).
• Xrb::Engine2::Object is the baseclass for the physical, tangible game objects -- Sprite and Compound. Itself, an Object can't move; see Entity. An Object not paired with an Entity is referred to as a "static object" because of its lack of movement/interaction. An Object has physical properties such as position, scale, and angle.
• Xrb::Engine2::Sprite is a subclass of Object and implements rectangular, single-texture game objects.
• Xrb::Engine2::Compound is a subclass of Object and implements conglomerates of arbitrary textured polygons. Compound will be covered in later lessons.
• Xrb::Engine2::Entity is the baseclass for game-specific interactive objects. An Entity is intangible by itself, and must be attached to an Object. An Object with an attached Entity is referred to as a "dynamic object". Dynamic objects are specially treated by the World to allow them to move within the game world and interact with other dynamic objects. Entity will be subclassed in each game's implementation to provide game-specific behavior (example subclasses could be SpaceShip, Missile, or even invisible things such as DamageArea). Entity will be covered in depth in later lessons.
• Xrb::Engine2::PhysicsHandler is the baseclass for game-specific collision detection and resolution. When a dynamic object is added to World, its Entity is passed to the PhysicsHandler. The game-specific implementation of PhysicsHandler may then track each Entity however it chooses. PhysicsHandler will be covered in detail in later lessons.

There are two additional classes which facilitate rendering and integration into the GUI widget hierarchy.

• Xrb::Engine2::WorldView is what actually renders the game world. The reason rendering is kept separate from World itself is for two reasons.
  • This design follows the document/view paradigm. Therefore, a single document (World) may have multiple views (WorldView).
  • This allows a separation of off-screen World processing and WorldView rendering which is necessary for real-time network games; the server performs off-screen World processing at some relatively low, fixed framerate, while the clients render WorldView at a relatively high framerate (interpolating the position/scale/angle of the game objects to create the illusion of arbitrarily smooth movement despite the low "real" framerate dictated by the server).
  As of September 2006, independent WorldView rendering is not implemented; rendering must run synchronously with off-screen World processing. Also as of September 2006, only top-down, parallaxed world rendering is implemented, though there's nothing stopping you from writing your own implementation. Other implementations could include isometric (e.g. Starcraft). In the future, WorldView will be made into an interface class, and specific implementations of it will be branched off (e.g. ParallaxedWorldView, IsometricWorldView, RadarView etc).
• Xrb::Engine2::WorldViewWidget is a subclass of Widget which contains a single instance of WorldView. In an earlier lesson I mentioned that everything visible in the game engine happens via use of a Widget or subclass thereof. This particular Widget is what ties the world rendering into the GUI hierarchy. It's very simple and straightforward, so you should probably never need to subclass or change it.

In this lesson we will create a simple game world consisting of a random mess of sprites, and a customized WorldView subclass in which to implement view zooming, rotation and movement.

Procedural Overview -- Items in bold are additions/changes to the previous lesson.

• Global declarations
  • Declare subclass of Engine2::WorldView specific to this app.
  • CreateAndPopulateWorld function which will dynamically allocate the World and Object instances which inhabit said World.
• Main function
  • Initialize the Pal and game engine singletons. Create the Screen object.
  • Execute game-specific code.
    • Create application-specific objects and GUI elements, and make necessary signals.
      • Create the game world via CreateAndPopulateWorld.
      • Create the WorldViewWidget and set it as screen's main widget.
      • Create the game-specific WorldView.
      • Attach the WorldView to the WorldViewWidget.
      • Attach the WorldView to the World.
    • Run the game loop
      • Calculate the Singleton::Pal().Sleep duration necessary to achieve the desired framerate.
      • Handle events (user and system-generated).
      • Perform off-screen processing, including game world processing.
      • Draw the Screen object's entire widget hierarchy.
    • Destroy application-specific objects.
      • Destroy WorldViewWidget object, which will destroy WorldView object.
      • Destroy World object, which will destroy all its ObjectLayers and Objects.
  • Delete the Screen object. Shutdown the Pal and game engine singletons.

Comments explaining previously covered material will be made more terse or deleted entirely in each successive lesson. If something is not explained well enough, it was probably already explained in previous lessons.

Code Diving!

 */
#include "xrb.hpp"                         // Must be included in every source/header file.

#include "xrb_engine2_objectlayer.hpp"     // For use of the Engine2::ObjectLayer class.
#include "xrb_engine2_sprite.hpp"          // For use of the Engine2::Sprite class.
#include "xrb_engine2_world.hpp"           // For use of the Engine2::World class.
#include "xrb_engine2_worldview.hpp"       // For use of the Engine2::WorldView class.
#include "xrb_engine2_worldviewwidget.hpp" // For use of the Engine2::WorldViewWidget class.
#include "xrb_event.hpp"                   // For use of the Event classes.
#include "xrb_eventqueue.hpp"              // For use of the EventQueue class.
#include "xrb_inputstate.hpp"              // For use of the InputState class (via Singleton::).
#include "xrb_input_events.hpp"            // For use of the EventMouseWheel class.
#include "xrb_math.hpp"                    // For use of the functions in the Math namespace.
#include "xrb_screen.hpp"                  // For use of the necessary Screen widget class.
#include "xrb_sdlpal.hpp"                  // For use of the SDLPal platform abstraction layer.

using namespace Xrb;                     // To avoid having to use Xrb:: everywhere.

/* 

Our customized WorldView class will implement view zooming, rotation and movement. The view will zoom in and out by mouse-wheeling-up and mouse-wheeling-down respectively. The view will rotate clockwise and counterclockwise by holding an ALT key and mouse-wheeling-up and mouse-wheeling-down respectively. View movement will be done by holding the left mouse button and dragging.

In order to process these mouse events, we will need to override a couple of methods in WorldView -- Xrb::Engine2::WorldView::ProcessMouseWheelEvent and Xrb::Engine2::WorldView::ProcessMouseMotionEvent. These methods do exactly what you think they do.

 */
class AwesomeWorldView : public Engine2::WorldView
{
public:

    // Trivial constructor which is just a frontend for WorldView's constructor.
    AwesomeWorldView (Engine2::WorldViewWidget *parent_world_view_widget)
        :
        Engine2::WorldView(parent_world_view_widget)
    { }

    // This method is called with all mouse wheel events received by this
    // WorldView object.  These aren't inherited from Widget (as WorldView
    // does not inherit Widget), but are called by their counterparts in
    // WorldViewWidget.
    virtual bool ProcessMouseWheelEvent (EventMouseWheel const *e)
    {
        /* 

Note that the accessor for ALT key state is on the event, and not on the Xrb::InputState singleton. This is because since events can be handled asynchronously, they must retain the key modifier states (e.g. ALT, CTRL) themselves.

 */
        // If either ALT key is pressed, we will rotate the view depending
        // on which of mouse-wheel-up or mouse-wheel-down this event indicates.
        if (e->IsEitherAltKeyPressed())
        {
            if (e->ButtonCode() == Key::MOUSEWHEELUP)
                RotateView(-15.0f); // Rotate 15 degrees clockwise.
            else
            {
                ASSERT1(e->ButtonCode() == Key::MOUSEWHEELDOWN);
                RotateView(15.0f); // Rotate 15 degrees counterclockwise.
            }
        }
        // Otherwise, we will zoom the view depending on which of
        // mouse-wheel-up or mouse-wheel-down this event indicates.
        else
        {
            if (e->ButtonCode() == Key::MOUSEWHEELUP)
                ZoomView(1.2f); // Zoom in by a factor of 1.2f
            else
            {
                ASSERT1(e->ButtonCode() == Key::MOUSEWHEELDOWN);
                ZoomView(1.0f / 1.2f); // Zoom out by a factor of 1.2f
            }
        }
        // Indicates that the event was used by this method.
        return true;
    }
    // This method is the mouse motion analog of ProcessMouseWheelEvent.
    virtual bool ProcessMouseMotionEvent (EventMouseMotion const *e)
    {
        // Only do stuff if the left mouse button was pressed for this event.
        if (e->IsLeftMouseButtonPressed())
        {
            // This transforms the screen-coordinate movement delta of the
            // mouse motion event into world-coordinates.
            FloatVector2 position_delta(
                ParallaxedScreenToWorld() * e->Delta().StaticCast<Float>() -
                ParallaxedScreenToWorld() * FloatVector2::ms_zero);
            // Move the view using the calculated world-coordinate delta.  We
            // negate the delta because by dragging the view down, the view
            // should move up; while dragging, the mouse cursor should always
            // stay on the same spot relative to the game world.
            MoveView(-position_delta);
            // Indicates that the event was used by this method.
            return true;
        }
        else
            // Event not used.
            return false;
    }
}; // end of class AwesomeWorldView

/* 

This is a helper function which will create our World instance and populate it with Sprites. The return value is the created World object.

 */
Engine2::World *CreateAndPopulateWorld ()
{
    // Create the world via the static method Engine2::World::Create.
    // The first parameter is a pointer to a PhysicsHandler object, however
    // we will not implement a PhysicsHandler in this lesson.
    Engine2::World *world = Engine2::World::CreateEmpty(NULL);
    // Decide some size for the ObjectLayer (arbitrary).
    static Float const s_object_layer_side_length = 1000.0f;
    /* 

Using the static method Xrb::Engine2::ObjectLayer::Create we will create the ObjectLayer in which we'll add all the Sprites. The parameters are:

• The World to which it belongs.
• A boolean value indicating wether or not positional wrapping is enabled. A wrapped ObjectLayer will repeat itself as if its opposing edges wrapped around and attached to themselves. Topologically speaking, a wrapped ObjectLayer maps to the surface of a 3 dimensional torus.
• The side length of the ObjectLayer's square domain.
• Depth of the QuadTree used to store the subordinate Objects. Don't worry about this one yet, it will be explained further in later lessons.
• The Z depth of the ObjectLayer. The meaning of this value is specific to the WorldView which is doing the rendering. In the case of parallaxed WorldViews, the ObjectLayers are stacked on top of one another, with their depths given by this value. The WorldView will use this value to calculate how large on-screen to render the Objects in each ObjectLayer.

We will then add the created ObjectLayer to the World object and set its main ObjectLayer (the meaning of this will be explained in later lessons).

 */
    Engine2::ObjectLayer *object_layer =
        Engine2::ObjectLayer::Create(
            world,                      // owner world
            false,                      // not wrapped
            s_object_layer_side_length, // side length
            6,                          // visibility quad tree depth
            0.0f);                      // z depth
    world->AddObjectLayer(object_layer);
    world->SetMainObjectLayer(object_layer);

    static Uint32 const s_object_count = 100;
    // Create a random mess of objects
    for (Uint32 i = 0; i < s_object_count; ++i)
    {
        // Create the sprite using the texture with given path
        Engine2::Sprite *sprite = Engine2::Sprite::Create("resources/interloper2_small.png");
        // Place the sprite randomly on the 1000x1000 ObjectLayer.  The
        // ObjectLayer is centered on the origin, so the valid range of
        // coordinates are [-500,500] for both X and Y.
        sprite->SetTranslation(
            FloatVector2(Math::RandomFloat(-500.0f, 500.0f), Math::RandomFloat(-500.0f, 500.0f)));
        // Size the sprite between 1% and 10% (arbitrary) of the ObjectLayer
        sprite->SetScaleFactor(s_object_layer_side_length * Math::RandomFloat(0.01f, 0.1f));
        // Set the angle of the sprite randomly
        sprite->SetAngle(Math::RandomFloat(0.0f, 360.0f));
        // Add the sprite to the object layer
        world->AddStaticObject(sprite, object_layer);
    }
    // Return the created World object.
    return world;
}

void CleanUp ()
{
    fprintf(stderr, "CleanUp();\n");
    // Shutdown the Pal and singletons.
    Singleton::Pal().Shutdown();
    Singleton::Shutdown();
}

int main (int argc, char **argv)
{
    fprintf(stderr, "main();\n");

    // Initialize engine singletons.
    Singleton::Initialize(SDLPal::Create, "none");
    // Initialize the Pal.
    if (Singleton::Pal().Initialize() != Pal::SUCCESS)
        return 1;
    // Set the window caption.
    Singleton::Pal().SetWindowCaption("XuqRijBuh Lesson 04");
    // Create Screen object and initialize given video mode.
    Screen *screen = Screen::Create(800, 600, 32, false);
    // If the Screen failed to initialize, print an error message and quit.
    if (screen == NULL)
    {
        CleanUp();
        return 2;
    }

    // Here is where the application-specific code begins.
    {
        /* 

Our application specific code consists of creating the game world and the two classes necessary to draw the game world via the GUI hierarchy.

 */
        // Create our sweet game world via a call to CreateAndPopulateWorld.
        Engine2::World *world = CreateAndPopulateWorld();
        // Create the WorldViewWidget as a child of screen.  This is what will
        // contain an instance of WorldView and will cause it to be rendered.
        Engine2::WorldViewWidget *world_view_widget = new Engine2::WorldViewWidget(screen);
        screen->SetMainWidget(world_view_widget);
        // Create an instance of our AwesomeWorldView, using the newly created
        // WorldViewWidget as its "parent".  Set the zoom factor so something
        // reasonable (though arbitrary).
        AwesomeWorldView *world_view = new AwesomeWorldView(world_view_widget);
        world_view->SetZoomFactor(0.004f);
        // Attach the newly created WorldView to the World object.
        world->AttachWorldView(world_view);
        /* 

Below, the game loop remains unchanged relative to the previous lesson except for a call to world->ProcessFrame(current_real_time) which handles all off-screen game computation.

 */
        // These values will be used below in the framerate control code.
        Float current_real_time = 0.0f;
        Float next_real_time = 0.0f;
        Float desired_framerate = 30.0f;
        // Run the game loop until the Screen no longer has the will to live.
        while (!screen->IsQuitRequested())
        {
            // Get the current real time and figure out how long to sleep, then sleep.
            current_real_time = 0.001f * Singleton::Pal().CurrentTime();
            Sint32 milliseconds_to_sleep = Max(0, static_cast<Sint32>(1000.0f * (next_real_time - current_real_time)));
            Singleton::Pal().Sleep(milliseconds_to_sleep);
            // Calculate the desired next game loop time
            next_real_time = Max(current_real_time, next_real_time + 1.0f / desired_framerate);

            // Process events until there are no more.
            Event *event = NULL;
            while ((event = Singleton::Pal().PollEvent(screen, current_real_time)) != NULL)
            {
                // Let the InputState singleton "have a go" at keyboard/mouse events.
                if (event->IsKeyEvent() || event->IsMouseButtonEvent())
                    Singleton::InputState().ProcessEvent(event);
                // Give the GUI hierarchy a chance at the event and then delete it.
                screen->ProcessEvent(event);
                Delete(event);
            }

            /* 

This call is what performs all off-screen game processing, mainly by World, and then in later lessons by PhysicsHandler and Entity subclasses. This is where all game logic and physics processing will happen.

 */
            world->ProcessFrame(current_real_time);

            // Turn the EventQueue crank, Perform off-screen GUI processing,
            // turn the EventQueue crank again, and then draw everything.
            screen->OwnerEventQueue()->ProcessFrame(current_real_time);
            screen->ProcessFrame(current_real_time);
            screen->OwnerEventQueue()->ProcessFrame(current_real_time);
            screen->Draw();
        }

        /* 

Although screen would automatically delete world_view_widget if left around, we must delete it ourselves in order to ensure proper deletion order relative to World. Deletion of WorldViewWidget will cause the deletion of the attached WorldView which will in turn automatically detach itself from World. Having no attached WorldViews is a necessary precondition for the destruction of World.

 */
        Delete(world_view_widget);
        Delete(world);
    }

    // Delete the Screen (and GUI hierarchy), "SHUT IT DOWN", and return success.
    Delete(screen);
    CleanUp();
    return 0;
}
/* 

Exercises

• Add code to AwesomeWorldView to smooth the zooming. You'll need to implement virtual void AwesomeWorldView::HandleFrame() for this. You can use the Xrb::FrameHandler::FrameTime method to retrieve the current time from inside HandleFrame.
• Add code to AwesomeWorldView to smooth the rotation. You'll need to implement virtual void AwesomeWorldView::HandleFrame() for this. You can use the Xrb::FrameHandler::FrameTime method to retrieve the current time from inside HandleFrame.
• Change the zooming code so that the zooming in 4 times in a row will result in an overall zoom-in of a factor of 2. Hint: the factor to zoom by should equal 2 when raised to the 4th power. You will need to use the Xrb::Math::Pow function.
• Screw with the sprite->SetTranslation call in CreateAndPopulateWorld and set the sprite's translation to somewhere outside the 1000x1000 grid of the ObjectLayer and see what happens.
• In CreateAndPopulateWorld, change the second parameter of Engine2::ObjectLayer::Create to true and see what happens.
• Screw with the sprite->SetTranslation call again and see what happens when you place a Sprite outside the domain of the ObjectLayer this time.
• In AwesomeWorldView::ProcessMouseMotionEvent, remove the negative sign from in front of position_delta in the call to MoveView, and see what the effects are. This new behavior might be preferable to some.
• Change CreateAndPopulateWorld so the sprites are not created with random positions and sizes, but form a spiral instead. Make each sprite's scale factor proportional to its distance from the origin, and set its angle such that it's facing away from the origin.
• Instead of creating a WorldViewWidget as the child of screen, make a grid Layout (e.g. row major with major count 2) and create several pairs of WorldViewWidget and WorldView, so that you have a 2x2 grid showing 4 total independent WorldViews. Remember to delete them at the end of the app-specific code. You can do this conveniently by deleting the Layout containing them.
• Disable the mouse-based view zooming/rotating/moving and implement virtual void AwesomeWorldView::HandleFrame() to:
  • Zoom in and out smoothly using the equation zoom factor = 0.008 * sin(k*time) + 0.01 where k is an arbitrary constant you can pick (I suggest k = 90). You'll need to use the Xrb::Engine2::WorldView::SetZoomFactor method.
  • Rotate counter/clockwise smoothly using the equation angle = 400 * cos(k*time) where k is an arbitrary constant you can pick (I suggest k = 90). You'll need to use the Xrb::Engine2::WorldView::SetAngle method.
  • Move the view in a circle using the vector equation position = 500 * (cos(k*time), sin(k*time)) where k is an arbitrary constant you can pick (I suggest k = 90). You'll need to use the Xrb::Engine2::WorldView::SetCenter method.
  You can use the Xrb::FrameHandler::FrameTime method to retrieve the current time from inside HandleFrame. Mess around with the equations and then show your kid brother how much cooler you are than him.

Thus concludes lesson04, you crazy almost-game-programming bastard, you.