Implementing Gameplay Gameplay Elements Elements Using Gamebryo
Chapter 1 – A Simple Framework for a Game Application Motivation Novice game developers, inspired by the by the latest game developed by Crytek by Crytek or Lionhead or EA, may want to begin programming gameplay without gameplay without thinking about the design and architecture of the game application. They want They want to work on code that makes the game fun! You might be able to create a simple game without considering the software design; however, if you if you try to build a complex game by adding features to ad hoc code, you will find that the cost to develop a new feature increases over time1. Further, the code will likely become more fragile, which can lead to cost overruns and project failure. We want to teach you how to use the Gamebryo system, while at the same time illustrating some of the of the design elements that you that you should consider when consider when building your game. ‐
You may be interested in constructing gameplay prototypes, developing a game as part of an academic project, or developing high quality commercial games. In any of these cases, when you choose to build your build your game using Gamebryo, you Gamebryo, you are not choosing to mod an existing shrink wrap game by adding your own content and tweaking AI. You AI. You will be building your own custom game engine from high quality, robust components that have been designed to allow you allow you the flexibility that the mod community does community does not enjoy. The goal of this of this tutorial series is to teach you teach you to develop gameplay features using Gamebryo, the centerpiece of your of your custom game engine. Each chapter will illustrate some Gamebryo feature, showing you how to integrate it with third party open source projects and your and your own code. ‐
‐
‐
Chapter 1 will begin to walk you through the development of some of the software needed to assemble a simple game engine using Gamebryo and other available components. The text will describe concepts and document the development of a of a small fragment of a of a game that implements the concepts. The code developed throughout this series is meant only to be illustrative, fairly easy to read and comprehend. It is not intended to represent the current best of breed practices in the game industry. We will provide with each chapter a set of recommended of recommended references where you can explore other ideas. The game development community is quite open, and it is easy to ‐
‐
‐
1
‐
Note that the gameplay first approach to game development can play an important role in the success of a large project, for example when used to build prototypes as a part of preproduction. Spore developer Maxis has incorporated gameplay prototyping gameplay prototyping into their development process for many years, years, especially in especially in the early phases early phases of development, of development, and the popularity of popularity of their their prior games is evidence that their approach is successful. The mod communities that grow out of the of the fan base of many of many first first person shooters are also able to quickly begin quickly begin working working on gameplay without without concern for software architecture, In this case, somebody else created the architecture for them, and though this enables game production to begin quickly, the ability to ability to add new features is limited. ‐
‐
Implementing Gameplay Elements Using Gamebryo learn from other developers by reading the proceedings of the Game Developers’ Conference or other industry conferences that occur each year around the world. So, with that, let us begin!
Game as a State Machine The concept of a finite state machine appears in most every game design. It is perhaps most often associated with artificial intelligence (AI), though developers do not implement AI using state machines exclusively and often use state machines for algorithms other than AI. The most fundamental use of the state machine in a game has nothing to do with game AI. The Wikipedia page for a finite state machine states that “A finite state machine (FSM) … is a model of behavior composed of a finite number of states, transitions between those states, and actions.” This definition might seem rather abstract, but it is easy to make sense of this. Consider the following characteristics, game screens in a typical game: •
•
•
•
•
• •
The opening splash screen that appears when you first put the game CD into the console and turn the console on: the game’s “boot” screen (StartupSplash) The main game user interface screen that lets you select a number of options such as begin a new game, load a saved game, visit an online gaming lobby, browse an inventory of magic spells gathered while playing the game, etc. (Home) The screen to begin a new game that lets you select a character to play, a level to load, and the difficulty level (StartNewGame) An “attract mode” in which the game plays back a cinematic sequence, originally developed for arcade games to attract players who might be standing nearby ( Attract) The “loading level…please wait…” screen that appears after you have selected a level to play (Loading) A popup window that displays when the game is paused (GamePaused ) The main gameplay window, which displays a 3D game world, the player’s character and NPCs, perhaps a small inset overhead map of the level, player statistics, inventory, and selected weaponry, etc. ( MainGamePlay)
All of these game screens display something different to the player. Each is independent, and only one can be in control at any instant in time (though more than one might be actively doing something). Each of these game screens is a game state, and so it begins to be easy to imagine a finite state machine that represents the overall flow of the major game screens of a game. Let’s look at a diagram of the states described above.
Implementing Gameplay Elements Using Gamebryo
Attract
StartupSplash
Home
StartNewGame
Loading
MainGamePlay
GamePaused
Here, an arrow has been drawn between the StartupSplash state to the Home state. This indicates a rather obvious transition. The StartupSplash state is active only until sufficient game assets are loaded to display the Home state, the main opening game user interface. The StartupSplash state is the face of the game as it boots. Let’s add another set of transitions. If no player interacts with the game for some period of time, say 60 seconds, the Home state will initiate a transition to the Attract state. After some time, or if the game detects that a player is doing something with a gamepad, the Attract state will initiate a transition back to the Home state. The following figure shows this new pair of transitions. Attract
StartupSplash
Home
StartNewGame
Loading
MainGamePlay
GamePaused
Without much difficulty, if you are familiar with games, you should be able to fill in the remaining basic transitions. The following figure illustrates a completed state machine transition diagram. (Though actually, there are other transitions that make sense here. For example, the player might be able to cancel out of the StartNewGame state, causing that state to transition back to the Home state.)
Implementing Gameplay Elements Using Gamebryo
Attract
StartupSplash
Home
StartNewGame
Loading
MainGamePlay
GamePaused
This very basic introduction to the concept of state machines should convince you that a typical game really, any game that gives the player any options can be built around a high level finite state machine. With a little bit of planning, it isn’t difficult to build these types of states into even the smallest of games, from the beginning. ‐
‐
Implementing a Simple Game Application using Gamebryo and a Simple Finite State Machine The remainder of this chapter will assemble a simple game application framework, implementing a subset of the states described above. StartupSplash
StartNewGame
MainGamePlay
GamePaused
The way our initial set of 4 states will work is extremely simple. It resembles a traditional application that displays a main window, but can change the way the user interacts by display popup dialog boxes, adding and removing panes and controls, etc. One key difference here is that, though only one state can be in control of the game application, any number of suspended states has the opportunity to perform actions interactively in time. These suspended states are not responding to controller input, but are playing animations or other special effects, deciding when to auto save a level in play, etc. The simplicity of this initial demo will make it easier for you to see how this works, how things fit together, and how you can exploit certain Gamebryo features ‐
Implementing Gameplay Elements Using Gamebryo within these game states. Here is a description of the specific behaviors we will implement in the 4 states. •
StartupSplash 1. Display a static full screen image showing the game title and information that the game is loading 2. For our chapter 1 tutorial code, simply wait for a few seconds to mimic the delay a player will experience while game assets loading from disk. The tutorial will load assets, but for now the assets aren’t so significant that the player would be bothered by the delay. 3. At the end of the waiting period, remove the full screen image and force a state change to StartNewGame StartNewGame 1. Display a list box with the names of all available playable characters, and allow the user to select from the list box with the mouse 2. Display a list box with the names of all the available game levels. For this chapter, only one game level will be available, and the user will not be able to change the selection 3. Display a button titled “Begin Game,” which when clicked with the left mouse button will force a state change to MainGamePlay, thus beginning a new game using the currently selected character and level 4. Display a 3D animated view of the currently selected character on a portion of the screen. The character should activate an idle animation. 5. Display a 3D view of the currently selected game level on a portion of the screen. 6. While waiting for the user to begin a game, respond to selection changes in the character list box by changing the 3D character view to reflect changed selections 7. Update the active animation of the currently selected character over time MainGamePlay 1. Load the selected level and selected character. Place the character at the location of a named spawn point node located in the game level’s scene graph. Make a camera named “DefaultCamera” the active camera. This camera is contained in the level scene graph 2. Animate the character in its idle state as time passes 3. Monitor the keyboard. When the user presses the ‘Q’ key, quit the application with no messages to the player 4. When the user presses the ‘P’ key, temporarily enter the GamePaused state. Note that this causes MainGamePlay to become suspended. 5. While suspended, do not respond to keyboard clicks or other user interface actions 6. While suspended, continue to update the character’s idle animation, so that the game level still has life even though gameplay is not continuing 7. When the state is resumed, resume responding to the keyboard GamePaused ‐
‐
•
‐
‐
•
•
Implementing Gameplay Elements Using Gamebryo 1.
Display a popup window UI over a portion of the screen that contains a single button labeled “Resume Game” 2. Respond to button clicks, and when the user selects the “Resume Game” button, remove the popup window and remove GamePaused from the state stack, causing the game to re enter the MainGamePlay state. ‐
Standard and Open Source Components
This tutorial series will use the NiApplication framework that is part of Gamebryo. Using this framework enables us to focus on integrating a simple finite state machine that is suitable for managing high level game state transitions and implementing the four game states we have selected. The tutorial code creates a new application class called GameObject, which extends the NiApplication class as shown in the class diagram below.
NiApplication
GameObject
We are going to integrate an open source state machine system contributed by James Boer to the book Game Programming Gems 5, titled “Large Scale Stack Based State Machines.” When you browse the source code, take note of James’ copyright and usage rights that are assigned within his source code. This simple framework was designed for things like high level game state, and is quite easy to use. It is the perfect choice for getting the initial game code up and running. The tutorial uses Boer’s implementation nearly verbatim from the CD distributed with the book. Only the following changes were applied. Comments in the StateManager.h and StateMachine.cpp files document these changes. Look for the label “EGT” along with descriptive text. ‐
•
‐
The pure virtual state interface class, IBaseState, was updated to be a Gamebryo reference counted object, e.g., it is now derived from the NiRefObject base class. The current simulation time was added as a parameter to the IBaseState::Update function, to enable concrete state classes to update animations, time state changes, etc. The StateManager class was updated to store smart pointers to reference counted state instances rather than raw pointers, to aid in memory cleanup. The StateManager class was modified to include the current simulation time in calls to IBaseState::Update on the active and suspended states. ‐
•
•
•
‐
We will be using one additional existing open source component. Since most of the states require a graphical user interface, we need classes that can implement widgets such as buttons and list
Implementing Gameplay Elements Using Gamebryo boxes. Emergent does provide as part of the Gamebryo distribution a simple user interface library, the NiUI* classes; however, the provided Gamebryo library includes only a very limited selection of controls. We will be using Crazy Eddie’s GUI System (CEGUI). One of Emergent’s support staff has taken the time to integrate CEGUI with Gamebryo, and we will exploit this integration. You can find the original demo integration in the Gamebryo support forum thread titled "CEGUI Gamebryo integration" located in the "Community Code Swap" folder, currently part of the “Download” forum. This code too is used in nearly pure form. The only change is to ensure the CEGUI system has been initialized at the time a CEGUI render click is constructed. These changes are documented in the CEGUIRenderClick.cpp file with the label “EGT” and descriptive text. Do keep in mind that these open source components may not be the only options available to you. For commercial projects, you may wish to consider using libraries provided by Emergent’s commercial partners, since tools and support for commercial options are often more cost effective and robust than open source code. Anatomy of a State
Above, we presented the basic concept of a game state, and the idea of transitions between them. Here, we will look at the anatomy of a single state, how the state has the opportunity to implement gameplay, and how state transitions are initiated. Any given state can be either active or inactive. All states that have been registered with the state manager are inactive by default, and do nothing as time passes. You can think of them as a library of states that are available for use when you need them. They are not on the state stack. Active states are those that are on the state stack, and all of these have the opportunity to do a variety of tasks, including: • • • • • • •
Load scene objects Modify the frame rendering system to display different overlays and user interfaces Modify scene graphs to spawn new objects, respond to triggers, etc. Display state specific screen overlays and controls Perform artificial intelligence or physics calculations Read from user interface devices (such as gamepads) to implement player interaction Update animations and rendering effects so that in game visuals are properly displayed ‐
‐
Note that a state that is made active will become inactive once again if the game removes the state from the state stack. States typically do not do any rendering. They can change the frame rendering configuration, adding, deleting, and modifying items. But the actual rendering is triggered within the NiApplication framework after state updates have completed for each frame. An active state can be suspended temporarily, allowing another state to take over for a while. An example of this is the MainGamePlay state, which is suspended while the game is paused.
Implementing Gameplay Elements Using Gamebryo Once constructed and registered with a state manager, each state object has 5 primary entry points, which override the following base class entry points: •
IBaseState::OnEnter:
the state manager calls this member function whenever the game is entering the state, and becoming active. It is here that a state can modify a scene graph, create a thread to do background loads, create a state specific graphical user interface (e.g., a pop up dialog box) to be rendered, etc. IBaseState::OnExit: the state manager calls this member function whenever the game is exiting the state, and the state is becoming inactive. The function should perform cleanup tasks here, freeing memory and unloading any state specific scene graph elements or other resources. IBaseState::OnOverride: the state manager calls this member function whenever another state is being pushed onto the state stack. The state remains active, but is suspended. It is allowed to do updates over time, but it is not the highest priority state. For example, the state manager will call this entry point on MainGamePlay whenever GamePaused becomes the active state at the top of the state stack. IBaseState::OnResume: the state manager calls this member function whenever this state moves to the top of the stack, becoming the highest priority state. For example, the state manager will call this entry point on MainGamePlay whenever GamePaused is made inactive. IBaseState::Update: Once per frame, the state manager calls this member function on all active states. This enables the active states to update themselves over time. ‐
‐
•
‐
•
•
•
The current game state can be changed most anywhere in the game code, but typically this occurs somewhere within the highest priority active state. For example, the StartupSplash state will force a transition to the StartNewGame state inside StartupSplash::Update, once it is done with bootstrap processing. The StartNewGame state will transition to MainGamePlay when the user presses a button, and MainGamePlay suspends itself by pushing GamePaused onto the state stack when the user performs some user interface action to pause the game. State transitions are activated via the StateManager class, using the following member functions. The game application must store a single instance of StateManager, and must make it available to any game state that needs to transition. •
•
•
StateManager::ChangeState:
Call this function to change the current highest priority active state. This does not change any lower priority states in the state stack. StateManager::PushState: Call this function to suspend the current highest priority state, push a new state onto the stack, and enter the new state. StateManager::PopState: Call this function to exit the highest priority state, pop it from the stack, and resume the next higher priority state.
Implementing Gameplay Elements Using Gamebryo NiApplication and Game Initialization
With those preliminary design notes out of the way, lets us look at the assembly of code for this chapter. Our game is built around the NiApplication framework that is used by the tutorials that are part of the Gamebryo distribution. Most of the internals of game application startup are handled deep within NiApplication. You can find a detailed description of that class in the Gamebryo documentation. Our GameObject class derives from NiApplication and overrides several of the NiApplication methods to support CEGUI integration and to support the state machine framework. The GameObject class includes two member variables: •
•
GameObject::m_StateManager.
The state machine manager instance that controls all state updates, the state stack, and transitions between states. GameObject::m_spGUIRenderClick. A smart pointer to the render click object that will display all CEGUI user interface elements.
Much of the GameObject class is boilerplate. It simply overrides various NiApplication base class methods to add support for the CEGUI system and the state machine system: •
•
•
•
This member function overrides the base class function, adding initialization of the state manager by calling StateManager::Init and registering all of the game states by calling GameObject::RegisterBaseStates. GameObject::Terminate. This member function disables the state manager by calling the StateManager::Term member function, then destroys the CEGUI render click, and finally calls the base class method. GameObject::CreateRenderer. This member function is largely a copy of the base class method. It has been modified to force the renderer to be windowed when the application is a DEBUG build, and full screen when the application is not a DEBUG build. GameObject::UpdateFrame. This member function calls the base class method, and then updates the active states by calling StateManager::Update. The state manager in turn calls the Update member function on all active states, allowing them to perform transient operations such as state specific animations and to make decisions as a function of time. GameObject::CreateFrame. This member function calls the base class method to create the render frame for the Gamebryo frame rendering system, and then calls another function, GameObject::InitializeGUIFramework, which initializes CEGUI and integrates it into the Gamebryo frame rendering system. GameObject::Initialize:
‐
•
Two pieces of the GameObject class require a bit more explanation. First,
the
member function, called from GameObject::CreateScene, is responsible for creating the CEGUI render click, which is the object that actually renders the user interface elements for the game. For detailed information on render clicks, see NiRenderClick or Frame Rendering System in the Gamebryo documentation. This method also configures the core CEGUI framework, telling it where resources are contained GameObject::InitializeGUIFramework
Implementing Gameplay Elements Using Gamebryo relative to the game application working folder. All runtime assets for the game are contained under the “assets” folder, and all user interface elements specifically are contained under the “assets/UI” folder. The method configures CEGUI so that it can locate 5 standard CEGUI asset types: schemes, imagesets, fonts, layouts, and looknfeels. Finally, this method loads a few CEGUI assets that are generally required for user interface elements within the game. It then adds the CEGUI render click to the screen space render step, so that GUI elements will be drawn, and creates a small, completely transparent background CEGUI window to be a container for any CEGUI elements a game state might need to create. If you use CEGUI in your game, you will need to have similar code to configure CEGUI. The important differences for your own game would be in the specific control schemes, fonts, etc., that you decide to pre load during game initialization, and perhaps the asset folder configuration. For the most part, this method too becomes boilerplate. (It is not the purpose of this tutorial to teach you about CEGUI. If you wish to learn more about these asset types, visit the CEGUI home page. If you are only interested in creating new user interface layouts for small projects, and aren’t interested in custom art, you can use the CELayoutEditor tool to graphically design new layouts.) ‐
The
game
initialization
code
becomes a bit more interesting within the GameObject::RegisterBaseStates member function. It is here that you will begin to see the design of the game come together. This method is quite simple, but sets up all 4 of the game states, by creating instances of them and registering them with the state manager. Note that the first registered class is StartupSplash, the only active state when the game begins. The state manager will immediately transition into this state during the first GameObject ::UpdateFrame call made once NiApplication starts the game simulation loop. Classification of the States
With the application initialized and states registered, let us now take a closer look at the individual state objects. We can classify states, where appropriate, in order to reuse some code across states. All states may need to know whether or not they have been suspended. The base state interface, IBaseState, does not directly provide this information, and the StateManager class also does not directly provide this information. So, for convenience, the code for this chapter derives an intermediate base class, GameBaseState, that overrides the OnOverride and OnResume member functions to set a member variable that tracks whether the state is suspended or not. It also provides an empty implementation of GameBaseState::Update, just in case any derived state does not need to perform transient tasks (e.g., some states might merely exist to respond to button clicks). Three of the states in our initial design will include user interface elements such as buttons, list boxes, and screen overlays: GamePaused , StartNewGame, and StartupSplash. All of these states will exploit CEGUI, and will use CEGUI window layouts to load the user interface controls for the state. It makes sense then to implement a base class for user interface classes. This class,
Implementing Gameplay Elements Using Gamebryo GameUIState,
is derived from GameBaseState. The classes for the three states listed above then derive from GameUIState, as shown in the class diagram below. Our one remaining state for this chapter, MainGamePlay, does not implement any user interface features other than a 3D render view of the game scene. Instead of deriving from GameUIState , it derives directly from GameBaseState.
NiRefObject
IBaseState
GameBaseState
StartNewGame
GameUIState
MainGamePlay
StartupSplash
GamePaused
Implementation of the Base User Interface State
Let us first look at the user interface base state class, GameUIState. The constructor for the GameUIState, and all derived states, contains two parameters, pcGUIImageSetFilename and pcGUILayoutFilename. The first parameter is the name of a CEGUI asset file with the extension “.imageset”. This file is an XML file that points to an image file (*.jpg, *.tga, etc.) and defines named rectangular areas within that image. The user interface states of our application use the named imageset as a decorative image to be displayed on the screen when the state is active. The second parameter is the name of a CEGUI asset file with the extension “.layout”. This is an XML file that defines a layout of user interface controls—buttons, list boxes, etc., as well as a background pane based on the decorative imageset. The visual appearance of the controls used in the layout is defined via CEGUI schemes and looknfeel objects, which reference imagesets and define which named rectangular areas are associated with a particular type of control, e.g., which rectangular sub images represent a button’s up and down states. The scheme and looknfeel also define how a particular control is mapped to CEGUI library code that represents the behavior of the control. ‐
Implementing Gameplay Elements Using Gamebryo During GameObject initialization, a number of schemes were loaded, and these schemes, together with the imageset and looknfeel objects that they implicitly loaded, are always available for any state’s layout to use. If you are using custom art, then your art team is responsible for creating all of the necessary CEGUI assets. The images used by the decorative background and controls alike can contain alpha channels, enabling your artists to paint interesting user interfaces with arbitrary shapes and borders. Your artists should take note that images referenced by CEGUI imagesets must have dimensions that are powers of two. ‐
‐
The constructor for GameUIState does very little. It simply caches the passed in imageset and layout names into instance member variables. The creation of the CEGUI user interface is implemented within the GameUIState::OnEnter and GameUIState::OnExit member functions. ‐
Whenever a user interface state is entered, and the state manager calls the state’s OnEnter member function, the base class will first initialize the state (e.g., load the decorative imageset and create the layout from file), if it is not initialized, and then it will append the state specific user interface layout as a child of the transparent background window that was created by the GameObject::InitializeGUIFramework member function. There is a convenient artifact that arises from appending the state specific user interface layout. The state specific layout becomes the last item in a list of layouts to be rendered, and so it is rendered on top of everything else. This is desirable, since we’d expect all suspended states to be obscured by the new state. Imagine that the MainGamePlay state contains user interface elements, and that the player presses a gamepad button to cause the game to pause. The pause state will add its own layout that will be rendered on top of the MainGamePlay layout—just as you would expect in a popup dialog box. ‐
‐
‐
Whenever a user interface state is exited, and the state manager calls a state’s OnExit member function, the base class will first remove the state specific layout from the CEGUI background window (thus revealing any other active state layouts that were hidden by the one exiting), and then will destroy the state specific layout and remove its imageset. The cleanup code is a way of reducing memory usage for states that are not active. Care must be taken for states that share a decorative imageset. The sample code does not handle this case. ‐
‐
Implementation of the StartupSplash State
This is the simplest of all the game states. Its layout displays a decorative background image called StartupSplashBackground . There are no controls at all. The behavior that this state implements is simply to wait for a while, and then force a transition to StartNewGame. The behavior is entirely implemented within the StartupSplashBackground::Update member function, using the code shown below: if (fCurrentTime >= 1.0) { StateManager &rStateManager = GameObject::GetStateManager();
Implementing Gameplay Elements Using Gamebryo rStateManager.ChangeState("StartNewGame"); }
Nothing could be simpler. Here, fCurrentTime is the current game simulation time, which is passed into the method as a parameter. After the simulation time reaches one second, the state uses the state manager to explicitly change the state to StartNewGame. The actual state change will occur during the next frame, when the state manager processes its internal event queue. (In a real game, of course, the splash state would typically do more than simply wait for some period of time before entering the next state.) Implementation of the StartNewGame State
This state is a bit more complex than StartupSplash. The two list boxes and the button are built into the CEGUI layout named “StartNewGame.layout”. The decorative background image that is used by the layout is called “StartNewGameBackground.imageset”. The decorative background in this case contains two transparent rectangular areas where the 3D views of the selected character and level are to be displayed. The control items in the layout are created and prepared for display as described above, by the base class, GameUIState. With this state we can look into the Gamebryo frame rendering system in a little more detail. The NiApplication boiler plate configuration code creates a number of render steps (in Gamebryo terms), including a shadow render step, a main render step intended to render 3D gameplay views, and a screen space render step, intended to render 2D overlays and user interface controls. In this state, we will use the main and screen space render steps. The main render step will display two render clicks. The first render click that we will create renders to a small portion of the game window, a viewport that has been allocated specifically to show an animated view of the currently selected 3D character. This character view is the first render click that will be rendered to the screen, as shown below. The number in the upper left corner of the render click indicates the order in which that render click is drawn to the screen. The large grey rectangle represents the full game application window. ‐
‐
‐
Implementing Gameplay Elements Using Gamebryo
1
3D Character View Render Click
Main GameObject Render Step
The second render click in the main render step will render a view of a second 3D scene that shows the selected level using a different camera. Again, this render click renders into a small viewport within the game window that has been allocated for the 3D level view.
1
2
3D Character View Render Click
3D Level View Render Click
Main GameObject Render Step
Implementing Gameplay Elements Using Gamebryo There are no more render clicks in the main render step. The next render step created by NiApplication is the screen space render step. In the GameObject initialization code, we attached the CEGUI user interface render click to this step, and so the user interface render click is drawn on top of the two 3D view render clicks. The user interface render click draws to the entire game window, and so if its scene contains opaque objects that cover the viewport areas drawn by the 3D views, the user interface will occlude the 3D views. The following image illustrates the display of the user interface render click on top of the prior render clicks. Here, the render click rectangle has been drawn slightly smaller than the outline shown for the full game window, simply to try and illustrate that it is being drawn on top. 3
CEGUI Render Click
1
2
3D Character View Render Click
3D Level View Render Click
Screen Space Render Step
The view above does not show any of the contents of the user interface render click. It merely illustrates the viewport and the fact that it is drawn on top of the prior render clicks—a layering effect. Below, the figure illustrates the elements of the StartNewGame state’s user interface: the decorative background image, the list box for character selection, the list box for level selection, and the “Begin Game” button. These are illustrated as though they were drawn at the same time, but in fact they too are drawn in sequence, as defined by the CEGUI layout. See the CEGUI documentation for more information on layering of CEGUI elements.
Implementing Gameplay Elements Using Gamebryo
3
CEGUI Render Click
1
2
3D Character View Render Click
3D Level View Render Click
Character List Box
Level List Box Begin Game
Screen Space Render Step
Note that, in the figure above, the 3D views show through the user interface. This illustrates the fact that the background imageset used by StartNewGame has transparent regions in the alpha channel of its texture, designed to reveal whatever was rendered underneath. Now, let’s look at how this configuration of the frame rendering system is accomplished. The StartNewGame class overrides the GameUIState::OnEnter method in order to do state specific initialization:
‐
•
•
•
Register a callback function, StartNewGame::ButtonClick, that will be called whenever the user clicks the “Begin Game” button. Generate a 3D view of the selected character, and populate the list box containing the names of the selectable characters. This is accomplished in a separate member function, StartNewGame::ConfigureSelectedCharacterView . Generate a 3D view of the selected level, and populate the level name list box. This is accomplished in a separate method, StartNewGame::ConfigureSelectedLevelView.
Creation of the 3D view of the selected character and level are somewhat involved. It is necessary to load Gamebryo assets and create new render views to display the 3D objects. The methods to create the character view and level view are very similar, so similar that this discussion will only describe the character view setup. The StartNewGame::ConfigureSelectedCharacterView member function is the entry point used to create the character view. It accomplishes several things:
Implementing Gameplay Elements Using Gamebryo
•
•
•
•
•
•
Uses the Gamebryo object streaming system to load a Gamebryo NiScene asset (a *.gsa file created by the Gamebryo SceneDesigner application) using the NiEntity library. This character selection scene contains all of the selectable characters and a camera that looks at each of them Configures a camera viewport to fit in the rectangular area associated with the character view StartNewGame::ConfigureAvailableCalls another member function, Characters , to parse the character NiScene and discover the names of all the playable characters Calls another method, StartNewGame::SelectCharacterImpl , to activate the camera for the initially selected character and to activate that camera within the appropriate viewport Updates the initial camera viewport and aspect ratio to match the rectangular area where characters are being displayed Creates a new render view and render click to use the camera to render the character scene in the appropriate place onscreen
Within this method, for chapter 1, the Gamebryo scene file name is hardcoded. Similarly, the rectangular area allocated for characters is hardcoded based on pixel coordinates that are built into the decorative imageset for this state. In later chapters, we will look at ways to use more data driven configurations, using runtime scripts.
‐
The StartNewGame::ConfigureAvailableCharacters function iterates through the entities contained in the character selection scene, searching for entities that have a master entity that have the text “[Characters]” in the name. It is the responsibility of your code and art teams to agree on naming conventions and standards for assets, to ensure that game logic is able to properly parse assets. In this case, for each discovered selectable character entity, the method creates a new entry in the character selection list box, which is called "StartNewGame/CharacterSel" in the CEGUI layout file for this state. The code populates a list box with the names of the characters it finds, and initially selects the first character in the list. The method does one more thing. It registers a callback function, StartNewGame::SelectCharacter, which will be called whenever the player selects a different character. The StartNewGame::SelectCharacterImpl function finds the currently selected character in the “StartNewGame/CharacterSel” list and locates the camera associated with that character in the scene. The code assumes that for every character, there is a camera that has the same name as the character but with the text “ Cam” appended. So, for the “Dragonman” character, the code expects to find a camera named “Dragonman Cam” that has been arranged within Scene Designer to look at the character named “Dragonman.” Here again is an example of code that requires coordination between code and art teams. If a camera is found, the code adjusts the camera’s viewport and aspect ratio to match the user interface area where the selected character is being displayed.
Implementing Gameplay Elements Using Gamebryo The StartNewGame::SelectCharacter callback function, which is called whenever the user clicks a different character name in the list box, simply calls through to StartNewGame:: SelectCharacterImpl to change the camera view. That completes configuration of the selected character view. Configuration for the selected level is similar; however, for this chapter only one level is available and the code is a bit simpler than for characters—no iteration though available levels and no callback to handle a change in level selection. The remaining code for this class concerns updating the state over time and responding to the button click that begins the game. The StartNewGame::Update function is called by the state manager once per frame. The code is rather simple: it calls the Update function on the NiScene objects associated with characters and levels. For the characters, these calls play whatever animation cycle was selected within Scene Designer . If the camera associated with the character was animated, this call would also update the camera along its path. Similarly, any animations that exist for the level select scene are also played here. Your art team is free to develop interesting effects that they would like to be be displayed and animated within the character and level select screen. The StartNewGame::ButtonClick function responds when the user clicks the “Begin Game” button. The only response is to change the state to MainGamePlay. The state manager will call the state’s OnExit method during the next update, just prior to calling MainGamePlay::OnEnter. The StartNewGame::OnExit function performs cleanup tasks, first removing the custom render clicks associated with the character and level 3D views, then calling the base class to perform standard user interface cleanup. This method does one other important task: it retrieves a pointer to the MainGamePlay state from the state manager, and calls a method in that state to tell the state which character and which level to use for the game. Implementing the MainGamePlay State
For this chapter, the MainGamePlay state is simple, at least when compared with StartNewGame. Ultimately, it does little more than display the selected level, create an instance of the selected character at a prescribed spawn point that is located in the level scene graph, then view the scene graph using a prescribed camera. As with StartNewGame, the code and art/design teams must agree on exactly how the scene will be presented during gameplay. Prior to the game entering the MainGamePlay state, the StartNewGame state will call MainGamePlay::BeginLevel on the inactive instance of MainGamePlay, which caches the NiScene object for the selected level and a pointer to a copy of the selected character entity. The character copy is created using MainGamePlay::SpawnCharacter, a function that instantiates a clone of a given character, and places it at a named spawn point. (In later chapters, the StartNewGame state might load a simplified version of the level for display prior to the game start, and in this case the MainGamePlay state would need to be delayed while the full level is
Implementing Gameplay Elements Using Gamebryo loaded. An intermediate state, such as the Loading state described near the beginning of this chapter, would be appropriate here.) The MainGamePlay::OnEnter function appends a render click to the GameObject’s main render step. Since there are no other scenes being rendered, and because there is (currently) no user interface, this render click is the only one that will render anything while MainGamePlay is at the top of the state stack. The new render click fills the application window with a single viewport that displays the selected level. This is the game play window. The function also searches for and activates a camera in the scene named “DefaultCamera.” When
the
player
game, the state calls the StartNewGame MainGamePlay::SpawnCharacter function, which clones the character that the player selected. By cloning the character, which was loaded into memory for the character selection, the game can avoid accessing the model from disk. If you study the function carefully, you will see that it clones the master entity of the player’s selected character, rather than the selected character itself. The reason why it is inappropriate to clone the selected character is that the selected character may have a custom translation and orientation that pose and animate the character as an artist intended it to be viewed during character selection, and this may be different from the in game pose. The in game character needs to be based on a canonical character state that places the character at the level origin, facing the negative y direction, with feet on the ground. Game logic can, therefore, very easily place the clone where it needs to be in the game level. The master entity has the canonical state. Once the master entity has been cloned, the method changes the value of the “Translation” property to place the clone at the spawn point location, sets the appropriate active animation sequence, and adds the clone to the list of entities affected by the light in the scene. Finally, the clone is added to the scene. ‐
begins
the
‐
The remaining code for this state deals with updating the state over time, and transitioning to other states. The MainGamePlay state class’ implementation of the IBaseState::Update virtual member function is a bit more complex than the implementation in states. As with the StartNewGame state, it calls the Update function on the appropriate NiScene object, which in turn updates rendering effects and animations. Beyond this, if the state is not suspended, it reads the keyboard and handles two keyboard commands: •
•
The ‘Q’ key will cause the state to issue a standard Windows message to shut down the application, to quite the game immediately. More sophisticated behavior would be to transition to another state allowing the user the option of saving the game, resuming the game, or exiting to the main menu. The ‘P’ key will cause the game to suspend this state, pushing the GamePaused state onto the state stack.
The method also contains placeholder comments for a variety of other things that can happen on every frame during gameplay, including:
Implementing Gameplay Elements Using Gamebryo
• • • •
artificial intelligence tasks such as path finding physics tasks that might not be handled automatically (within any animation updates) scripting tasks and other state specific tasks ‐
We will fill in these other per frame tasks as we build this game up over the chapters to come. ‐
As with the other states, the MainGamePlay::OnExit function performs cleanup tasks. In this case, the explicit cleanup code is simply to remove the render click that was added to render the level. The method also dereferences the level’s NiScene object, which might cause it to be destructed (if it is not referenced elsewhere). The scene owns the cloned character, and so the non smart pointer to the character is set to zero to avoid potential use of an object that might have been destructed. ‐
Implementing the GamePaused State
GamePaused is the last state that we are implementing for chapter 1.
It is a user interface state, and so its class derives from GameUIState and utilizes a CEGUI *.layout file to obtain its controls. This state has a single control, a button that the user can press to resume the game. Its GamePaused::Initialize function registers a callback function, GamePaused::ButtonClick, that the CEGUI system will call whenever the button is clicked. That callback function simply pops the state off of the state manager’s stack, causing the state to exit, and causing the prior state to resume. In this case, the only state that can enter GamePaused is MainGamePlay. So, when GamePaused responds to the button click, at the next GameObject::UpdateFrame call performed by NiApplication, the game will resume the game.
Final Remarks and Lessons to be Learned from the Chapter 1 Demo Code Now that the 4 game states are fully implemented, the game is ready to run! Although some of the configuration code can be a bit tedious, it is largely boilerplate and easily written once in a base class, then reused forever. For example, our GameUIState base class manages all user interface layouts for display, and manages cleanup when a state goes inactive. The derived classes only need to register state specific callbacks for control interactions, and then respond to those controls. The code for this chapter is rather simple, and presents only one approach to managing high level states in a game. Hopefully, as you observed the code developed here, and learned how the pieces work together, you began to better understand how to think about software architecture and structure as you design your own game. ‐
We recommend that you now take the time to run the code in debug mode, with break points set at the top of the OnEnter, OnExit, OnOverride, and OnResume functions of each state, as StateManager::ChangeState, well as on lines of code that call StateManager::PushState, and StateManager::PopState. This will enable you to experience the state diagram transitions directly, and may deepen your appreciation for the
Implementing Gameplay Elements Using Gamebryo simplicity of the system. Also, you may be interested in browsing the HTML documentation for the chapter’s code. Open the HTML file, index.html, located in the Chapter1/docs/html folder, to view the documentation. One important lesson you should learn from this chapter is that it is vitally important for the art team (including designers) and code and script developers to come to an agreement on naming conventions and organizational conventions for all art assets. Establishing these conventions must be one of the first things you do during preproduction, regardless of whether you are working on an AAA title or a student or hobby game project! If you fail to establish conventions, and use them, you will eventually waste a significant amount of time correlating code, script, and assets. So take heed!
File Directory Structure for the Tutorial Code The classes described above load various CEGUI and Gamebryo assets, from time to time. All of the assets are located in a hierarchy of subfolders under the “assets” folder, which must be directly underneath the application working folder. Following is a summary of the hierarchy of asset folders used by this chapter’s code. ‐
‐
CEGUI_Integration
Objects that integrate CEGUI into Gamebryo
Chapter1
Root folder for the Chapter 1 demo code The configuration file for doxygen, used to generate source code documentation, is contained here. The Visual Studio project builds the game executable files into this folder, and this is the working folder when running the game in debug mode, since the assets are directly underneath
SourceWin32
Source files for main game app and base classes The project solution file and project file for Visual Studio 2005 .NET are here
States
Source files for concrete game state classes
Utilities
Source files for various utility functions
Docs
Output folder for doxygen, this folder contains formatted documentation for the source code
Assets Characters Dragonman
Root folder for game runtime assets Root folder for game character assets Folder containing the Dragonman character and animations
Phoenix
Folder containing the Phoenix character and animations
Models
Scenes
Folder containing general game models Folder containing game scene files, created with the Gamebryo SceneDesigner. These scenes reference items in the characters and models folders
UI
Root folder for all CEGUI user interface assets Configs
CEGUI config schema files
Implementing Gameplay Elements Using Gamebryo Fonts
CEGUI font files
Imagesets
CEGUI image sets
Layouts
CEGUI layouts. Layouts define the look and layout of user interface controls for those states that display user interfaces. The layouts can be created using the CEGUI tool, CELayoutEditor.
Looknfeel
CEGUI look-n-feel files
Schemes
CEGUI scheme files
Other Resources and References Emergent Game Technologies, “Introduction to the Frame Rendering System” in the Gamebryo Documentation Emergent Game Technologies, “Introduction to NiApplication” in the Gamebryo Documentation Emergent Game Technologies, “NiEntity Introduction” in the Gamebryo Documentation Crazy Eddie’s GUI System Website: http://www.cegui.org.uk/wiki/index.php/Main_Page Boer, James, “Large Scale Stack Based State Machines,” Game Programming Gems 5, Charles River Media, 2005. ‐
‐
Exercises 1. How would you modify the high level game state machine illustrated above to include an online game lobby? 2. How would you extend the example application to represent the full collection of states illustrated above? 3. How would you add an in game “mini game” to the state machine? ‐
