Eric Lengyel: Created page with "This page contains the complete source code for the `SimpleBall` example game module. See the Simple Games page for more information about the basic examples. == SimpleBall.h == #ifndef SimpleBall_h #define SimpleBall_h #include "C4Application.h" #include "C4World.h" #include "C4Input.h" #include "C4Cameras.h" #include "C4Interface.h" #include "C4Particles.h" // Every application/game module needs to declare a function ca..."

2023-09-12T21:41:35Z

Created page with "This page contains the complete source code for the <code>SimpleBall</code> example game module. See the Simple Games page for more information about the basic examples. == SimpleBall.h == <syntaxhighlight lang="c++"> #ifndef SimpleBall_h #define SimpleBall_h #include "C4Application.h" #include "C4World.h" #include "C4Input.h" #include "C4Cameras.h" #include "C4Interface.h" #include "C4Particles.h" // Every application/game module needs to declare a function ca..."

New page

This page contains the complete source code for the <code>SimpleBall</code> example game module. See the [[Simple Games]] page for more information about the basic examples.

== SimpleBall.h ==

<syntaxhighlight lang="c++">
#ifndef SimpleBall_h
#define SimpleBall_h

#include "C4Application.h"
#include "C4World.h"
#include "C4Input.h"
#include "C4Cameras.h"
#include "C4Interface.h"
#include "C4Particles.h"

// Every application/game module needs to declare a function called CreateApplication()
// exactly as follows. (It must be declared extern "C", and it must include the tag
// C4_MODULE_EXPORT.) The engine looks for this function in the DLL and calls
// it to create an instance of the subclass of the Application class that the
// application/game module defines.

extern "C"
{
C4_MODULE_EXPORT C4::Application *CreateApplication(void);
}

namespace SimpleBall
{
using namespace C4;

// These are action types used to define action bindings in the
// Input Manager. If the four-character code for an action is
// 'abcd', then any input control (there can be more than one)
// bound to %abcd triggers the associated action.

enum : ActionType
{
kActionForward = 'frwd',
kActionBackward = 'bkwd',
kActionLeft = 'left',
kActionRight = 'rght',
kActionUp = 'jump',
kActionDown = 'down'
};

// Model types are associated with a model resource using the ModelRegistration
// class. Models are registered with the engine in the Game constructor.

enum : ModelType
{
kModelBall = 'ball'
};

// New controller types are registered with the engine in the Game constructor.

enum : ControllerType
{
kControllerBall = 'ball'
};

// This is the type of our custom particle system.

enum : ParticleSystemType
{
kParticleSystemSpark = 'sprk'
};

// New locator types are registered with the engine in the Game constructor.
// The 'spec' locator is used to specify where the spectator camera should
// be positioned when a world is loaded.

enum : LocatorType
{
kLocatorSpectator = 'spec'
};

// An Action object represents an input action that can be triggered by some
// input control, such as a key on the keyboard or a button on a gamepad.
// The HandleEngage() and HandleDisengage() methods are called when the button
// is pressed and released, respectively. Actions are registered with the Input
// Manager when the Game class is constructed.

class MovementAction : public Action
{
private:

uint32 movementFlag;

public:

MovementAction(ActionType type, uint32 flag);
~MovementAction();

void HandleEngage(void) override;
void HandleDisengage(void) override;
};

// Controllers are used to control anything that moves in the world.
// New types of controllers defined by the application/game module are
// registered with the engine when the Game class is constructed.
//
// The BallController inherits from the built-in rigid body controller,
// which handles the ball's motion and collision detection. We are only
// adding a little bit of functionality that causes a particle system
// to be created when a ball hits another ball.

class BallController final : public RigidBodyController
{
private:

BallController(const BallController& ballController);

Controller *Replicate(void) const override;

public:

BallController();
~BallController();

static bool ValidNode(const Node *node);

void PreprocessController(void) override;

RigidBodyStatus HandleNewRigidBodyContact(const RigidBodyContact *contact, RigidBodyController *contactBody) override;
};

// The SparkParticleSystem class implements a simple particle system that
// creates a small burst of sparks.

class SparkParticleSystem : public LineParticleSystem
{
// This friend declaration allows the particle system registration object
// to construct a SparkParticleSystem object using the private default constructor.

friend class ParticleSystemReg<SparkParticleSystem>;

private:

enum {kMaxParticleCount = 100};

int32 sparkCount;

// This is where information about each particle is stored.

ParticlePool<> particlePool;
Particle particleArray[kMaxParticleCount];

SparkParticleSystem();

bool CalculateBoundingSphere(BoundingSphere *sphere) const override;

public:

SparkParticleSystem(int32 count);
~SparkParticleSystem();

void PreprocessNode(void) override;
void AnimateParticles(void) override;
};

// The StartWindow class is a simple example of a window that handles button clicks.
// We add the Global base class so that a pointer to the window can be tracked easily.

class StartWindow : public C4::Window, public Global<StartWindow>
{
private:

WidgetObserver<StartWindow> startButtonObserver;
WidgetObserver<StartWindow> quitButtonObserver;

void HandleStartButtonEvent(Widget *widget, const WidgetEventData *eventData);
void HandleQuitButtonEvent(Widget *widget, const WidgetEventData *eventData);

public:

StartWindow();
~StartWindow();

void PreprocessWidget(void) override;

bool HandleKeyboardEvent(const KeyboardEventData *eventData) override;
};

// The application/game module will usually define a subclass of the World
// class so that extra information can be associated with the current world.
// In this case, an instance of the SpectatorCamera class is included
// with the world. A new instance of this World subclass should be returned
// when the Game::CreateWorld() function is called (see below).

class GameWorld : public World
{
private:

SpectatorCamera spectatorCamera;

static const LocatorMarker *FindSpectatorLocator(const Zone *zone);

public:

GameWorld(const char *name);
~GameWorld();

SpectatorCamera *GetSpectatorCamera(void)
{
return (&spectatorCamera);
}

WorldResult PreprocessWorld(void) override;
void RenderWorld(void) override;
};

// Every application/game module needs to define a subclass of the Application
// class to serve as the primary interface with the engine. This subclass is
// created and returned to the engine in the CreateApplication() function.
// There should be only one instance of this class, and a pointer to it is
// declared below.

class Game : public Application, public Global<Game>
{
private:

ModelRegistration ballModelReg;
ControllerReg<BallController> controllerReg;
ParticleSystemReg<SparkParticleSystem> sparkParticleSystemReg;
LocatorRegistration locatorReg;

InputMgr::KeyCallback *prevEscapeCallback;
void *prevEscapeCookie;

MovementAction *forwardAction;
MovementAction *backwardAction;
MovementAction *leftAction;
MovementAction *rightAction;
MovementAction *upAction;
MovementAction *downAction;

static World *CreateWorld(const char *name, void *cookie);

static void EscapeCallback(void *cookie);

public:

Game();
~Game();
};

// This is a pointer to the one instance of the Game class through which
// any other part of the application/game module can access it.

extern Game *TheGame;

// This is a pointer to the start window. We only keep this around so that
// we can delete the window before exiting if it's still on the screen.

extern StartWindow *TheStartWindow;
}

#endif
</syntaxhighlight>

== SimpleBall.cpp ==

<syntaxhighlight lang="c++">
#include "SimpleBall.h"

using namespace SimpleBall;

// This is the definition of the pointer to the Game class global.
// It should be initialized to nullptr, and its value will be set by
// the Game class constructor.

Game *SimpleBall::TheGame = nullptr;

// This is the definition of the pointer to the StartWindow class global.
// It should be initialized to nullptr, and its value will be set by
// the StartWindow class constructor.

StartWindow *SimpleBall::TheStartWindow = nullptr;

C4::Application *CreateApplication(void)
{
// This function should simply return a pointer to a new instance of
// the Application class. Normally, the application/game module will
// define a subclass of the Application class (in this case, the
// Game class) and return a pointer to a new instance of that type.

// This function is called exactly one time right after the
// application/game module DLL is loaded by the engine. The returned
// class is destroyed via the virtual destructor of the Application
// class right before the application/game module DLL is unloaded.

return (new Game);
}

MovementAction::MovementAction(ActionType type, uint32 flag) : Action(type)
{
// Each instance of the MovementAction class represents a movement
// in a single direction, as indicated by the flag parameter.
// All of the MovementAction instances are constructed in the
// Game class constructor.

movementFlag = flag;
}

MovementAction::~MovementAction()
{
}

void MovementAction::HandleEngage(void)
{
// This function is called when the input control associated with this
// particular action is engaged (e.g., a key was pressed).

World *world = TheWorldMgr->GetWorld();
if (world)
{
// If there's currently a world loaded, apply the movement to
// the spectator camera.

SpectatorCamera *camera = static_cast<GameWorld *>(world)->GetSpectatorCamera();
camera->SetSpectatorFlags(camera->GetSpectatorFlags() | movementFlag);
}
}

void MovementAction::HandleDisengage(void)
{
// This function is called when the input control associated with this
// particular action is disengaged (e.g., a key was released).

World *world = TheWorldMgr->GetWorld();
if (world)
{
// If there's currently a world loaded, remove the movement from
// the spectator camera.

SpectatorCamera *camera = static_cast<GameWorld *>(world)->GetSpectatorCamera();
camera->SetSpectatorFlags(camera->GetSpectatorFlags() & ~movementFlag);
}
}

BallController::BallController() : RigidBodyController(kControllerBall)
{
// This constructor is called when a new ball model is created.
}

BallController::BallController(const BallController& ballController) : RigidBodyController(ballController)
{
// This constructor is called when a ball controller is cloned.
}

BallController::~BallController()
{
}

Controller *BallController::Replicate(void) const
{
return (new BallController(*this));
}

bool BallController::ValidNode(const Node *node)
{
// This function is called by the engine to determine whether this
// specific type of controller can be assigned to the particular
// node passed in through the node parameter. This function should
// return true if it can control the node, and otherwise it should
// return false. In this case, the controller can only be applied
// to model nodes.

return (node->GetNodeType() == kNodeModel);
}

void BallController::PreprocessController(void)
{
// This function is called once before the target node is ever
// rendered or moved. The base class PreprocessController() function
// should always be called first, and then the subclass can do whatever
// preprocessing it needs to do. In this case, we set a few of the
// ball's physical parameters and give it a random initial velocity.

RigidBodyController::PreprocessController();

SetRestitutionCoefficient(0.99F);
SetSpinFrictionMultiplier(0.1F);
SetRollingResistance(0.01F);

SetLinearVelocity(Random::RandomUnitVector3D() * 2.0F);
}

RigidBodyStatus BallController::HandleNewRigidBodyContact(const RigidBodyContact *contact, RigidBodyController *contactBody)
{
// This function is called when the ball makes contact with another rigid body.
// If we hit another ball, then we add a sound effect and some sparks to the world.

if (contactBody->GetControllerType() == kControllerBall)
{
Node *node = GetTargetNode();
World *world = node->GetWorld();
Point3D position = node->GetWorldTransform() * contact->GetContactPosition();

OmniSource *source = new OmniSource("model/Ball", 40.0F);
source->SetNodePosition(position);
world->AddNewNode(source);

SparkParticleSystem *sparks = new SparkParticleSystem(20);
sparks->SetNodePosition(position);
world->AddNewNode(sparks);
}

return (kRigidBodyUnchanged);
}

SparkParticleSystem::SparkParticleSystem(int32 count) :

// Initialize the base class for line particles
// and tell it where the particle pool is.
LineParticleSystem(kParticleSystemSpark, &particlePool, "particle/Spark1"),

// Initialize the particle pool by telling it where the array
// of Particle structs is and how big it is.
particlePool(kMaxParticleCount, particleArray)
{
// The SparkParticleSystem node creates a small burst of sparks
// and then self-destructs when all of them have burned out.

sparkCount = count;
SetLengthMultiplier(4.0F);
SetParticleSystemFlags(kParticleSystemSelfDestruct);
}

SparkParticleSystem::SparkParticleSystem() :
LineParticleSystem(kParticleSystemSpark, &particlePool, "particle/Spark1"),
particlePool(kMaxParticleCount, particleArray)
{
// This constructor gets used when the particle system is being loaded from
// a saved game. In this case, we don't need to initialize anything.
}

SparkParticleSystem::~SparkParticleSystem()
{
}

bool SparkParticleSystem::CalculateBoundingSphere(BoundingSphere *sphere) const
{
// Just return a sphere that's big enough to always enclose
// all of the particles. This is in object-space coordinates.

sphere->SetCenter(0.0F, 0.0F, 0.0F);
sphere->SetRadius(20.0F);
return (true);
}

void SparkParticleSystem::PreprocessNode(void)
{
// This function creates the spark particles.

// Always call the base class PreprocessNode() function.
LineParticleSystem::PreprocessNode();

// If there's already a particle in the system, then the node was loaded from
// a saved game. We only create new particles if the particle system is empty.

if (!GetFirstParticle())
{
// Calculate the world-space center.
Point3D center = GetSuperNode()->GetWorldTransform() * GetNodePosition();

const Vector2D *trig = Math::GetTrigTable();

int32 count = sparkCount;
for (machine a = 0; a < count; a++)
{
// Grab a new unused particle from the pool.
Particle *particle = particlePool.NewParticle();
if (!particle)
{
break;
}

particle->emitTime = 0; // Particle appears right away.
particle->lifeTime = 500 + Random::RandomInteger(750); // Particle lives 500-1250 milliseconds.
particle->radius = 0.02F; // The radius is 20 mm.
particle->color.Set(1.0F, 1.0F, 0.1F, 1.0F); // It's yellow.
particle->orientation = 0; // This doesn't matter for line particles.
particle->position = center; // It starts at the effect's center.

// Calculate a random velocity in a random direction.
float speed = Random::RandomFloat(0.004F);
const Vector2D& csp = trig[Random::RandomInteger(128)];
const Vector2D& cst = trig[Random::RandomInteger(256)];
particle->velocity.Set(cst.x * csp.y * speed, cst.y * csp.y * speed, csp.x * speed);

// Add the particle to the particle system.
AddParticle(particle);
}
}
}

void SparkParticleSystem::AnimateParticles(void)
{
// This function is called once per frame to move the particles.

// Times are in milliseconds.
int32 dt = TheTimeMgr->GetDeltaTime();
float fdt = TheTimeMgr->GetFloatDeltaTime();

Particle *particle = GetFirstParticle();
while (particle)
{
// Get the next particle here in case the current one is removed from the system.
Particle *next = particle->nextParticle;

int32 life = (particle->lifeTime -= dt);
if (life > 0)
{
// Update velocity with gravity.
particle->velocity.z += Const::gravity * fdt;

// Move the particle and see if it hit the floor plane at z = 0.
float z1 = particle->position.z - particle->radius;
particle->position += particle->velocity * fdt;
float z2 = particle->position.z - particle->radius;
if (z1 * z2 <= 0.0F)
{
// The particle hit the floor, so reflect its velocity and remove some energy.
particle->position.z = 0.05F - z2;
particle->velocity.z *= -0.5F;
}

// If the particle is nearing the end of its life, fade it out.
if (life < 100)
{
particle->color.alpha = (float) life * 0.01F;
}
}
else
{
// Particle burned out.
FreeParticle(particle);
}

particle = next;
}
}

// The StartWindow constructor initializes the Window base class with the name of the panel
// resource to load. The observer members are initialized with the functions that are
// called when the "Start" and "Quit" push buttons in the window post activate events.

StartWindow::StartWindow() :
Window("panel/SimpleBall"),
Global<StartWindow>(TheStartWindow),
startButtonObserver(this, &StartWindow::HandleStartButtonEvent),
quitButtonObserver(this, &StartWindow::HandleQuitButtonEvent)
{
}

StartWindow::~StartWindow()
{
}

void StartWindow::PreprocessWidget(void)
{
// We must call the Window base class PreprocessWidget() function first to initialize
// the internal structures that are used to search for widgets.

Window::PreprocessWidget();

// Assign observers to the push button widgets named "Start" and "Quit".

Widget *button = FindWidget("Start");
button->SetObserver(&startButtonObserver);

button = FindWidget("Quit");
button->SetObserver(&quitButtonObserver);
}

bool StartWindow::HandleKeyboardEvent(const KeyboardEventData *eventData)
{
if (eventData->eventType == kEventKeyDown)
{
if (eventData->keyCode == kKeyCodeEscape)
{
// The Escape key was pressed while this window had the focus.
// If a world is loaded, then just delete the window and return to gameplay.

if (TheWorldMgr->GetWorld())
{
delete this;
return (true);
}
}
}

return (false);
}

void StartWindow::HandleStartButtonEvent(Widget *widget, const WidgetEventData *eventData)
{
// This function is called whenever the "Start" push button posts an event.

if (eventData->eventType == kEventWidgetActivate)
{
// If the widget was activated, then the user clicked the push button.
// Delete the window and load a world to play.

delete this;

TheWorldMgr->LoadWorld("world/SimpleBall");
}
}

void StartWindow::HandleQuitButtonEvent(Widget *widget, const WidgetEventData *eventData)
{
// This function is called whenever the "Quit" push button posts an event.

if (eventData->eventType == kEventWidgetActivate)
{
// If the widget was activated, then the user clicked the push button.
// Quit the engine.

TheEngine->Quit();
}
}

GameWorld::GameWorld(const char *name) :
World(name),
spectatorCamera(2.67F, 1.0F, 0.3F)
{
// This constructor is called when the Game::CreateWorld() function is
// called to create a new world class. The world hasn't actually been loaded
// from disk yet when we get here.
}

GameWorld::~GameWorld()
{
}

const LocatorMarker *GameWorld::FindSpectatorLocator(const Zone *zone)
{
// Iterate through all of the markers in the zone.

const Marker *marker = zone->GetFirstMarker();
while (marker)
{
if (marker->NodeEnabled())
{
MarkerType type = marker->GetMarkerType();
if (type == kMarkerLocator)
{
const LocatorMarker *locator = static_cast<const LocatorMarker *>(marker);
if (locator->GetLocatorType() == kLocatorSpectator)
{
return (locator);
}
}
}

// Get the next marker in the list.

marker = marker->GetNextListElement();
}

// Recursively look in all of the subzones.

const Zone *subzone = zone->GetFirstSubzone();
while (subzone)
{
const LocatorMarker *locator = FindSpectatorLocator(subzone);
if (locator)
{
return (locator);
}

subzone = subzone->ListElement<Zone>::GetNextListElement();
}

return (nullptr);
}

WorldResult GameWorld::PreprocessWorld(void)
{
// The PreprocessWorld() function is called after the world has been constructed.
// We must always call the base class PreprocessWorld() function first. If it
// returns an error, then we just return the same result code.

WorldResult result = World::PreprocessWorld();
if (result != kWorldOkay)
{
return (result);
}

// The world is now completely loaded. We search for a locator node that represents the
// spectator camera's starting position. It has a locator type of kLocatorSpectator.

const LocatorMarker *marker = FindSpectatorLocator(GetRootNode());
if (marker)
{
// A spectator marker was found.
// Set the spectator camera's initial position and orientation.

const Vector3D direction = marker->GetWorldTransform()[0];
float azimuth = Arctan(direction.y, direction.x);
float altitude = Arctan(direction.z, Sqrt(direction.x * direction.x + direction.y * direction.y));

spectatorCamera.SetCameraAzimuth(azimuth);
spectatorCamera.SetCameraAltitude(altitude);
spectatorCamera.SetNodePosition(marker->GetWorldPosition());
}
else
{
// A spectator marker was not found.
// Put the spectator camera one meter above the origin by default.

spectatorCamera.SetNodePosition(Point3D(0.0F, 0.0F, 1.0F));
}

// Set the world's current camera to be our spectator camera.
// The world will not render without a camera being set.

SetWorldCamera(&spectatorCamera);
return (kWorldOkay);
}

void GameWorld::RenderWorld(void)
{
// This function is called once per frame to render the world.
// The subclass may do whatever it needs to before or after rendering,
// but at some point must call World::RenderWorld().

World::RenderWorld();
}

Game::Game() :

// This is the constructor for the main application/game module class.
// This class is created by the CreateApplication() function, which is
// called right after the application/game DLL is loaded by the engine.
// We initialize the global pointer to the current game instance first.

Global<Game>(TheGame),

// A model registration represents a model that can be instanced.
// This particular declaration associates the kModelBall type with the
// model named "model/Ball.mdl". The fourth parameter tells the engine
// to precache the model resource, and the last parameter specifies
// the default controller type to assign to models of type kModelBall.

ballModelReg(kModelBall, "Bouncing Ball", "model/Ball", kModelPrecache, kControllerBall),

// A controller registration tells the engine about an application-defined type of
// controller and registers its name. In this case, the name "Bouncing Ball" will
// appear in the list of available controllers in the World Editor for any node that
// is determined to be a valid target node by the BallController::ValidNode() function.

controllerReg(kControllerBall, "Bouncing Ball"),

// A particle system registration tells the engine about an application-defined
// type of particle system and registers its name.

sparkParticleSystemReg(kParticleSystemSpark, "Sparks"),

// Locator markers are registered so that the World Editor
// can display their names in the Markers page.

locatorReg(kLocatorSpectator, "Spectator Camera")
{
// This sets the function that is called when the user hits the
// escape key during gameplay. We save the old function so that
// it can be restored when the game DLL is unloaded.

prevEscapeCallback = TheInputMgr->GetEscapeCallback();
prevEscapeCookie = TheInputMgr->GetEscapeCookie();
TheInputMgr->SetEscapeCallback(&EscapeCallback, this);

// This registers our world class constructor with the World Manager.
// We only need to do this if we have defined a subclass of the World
// class that holds extra information.

TheWorldMgr->SetWorldCreator(&CreateWorld);

// These create the movement actions that are used to fly the spectator camera around.

forwardAction = new MovementAction(kActionForward, kSpectatorMoveForward);
backwardAction = new MovementAction(kActionBackward, kSpectatorMoveBackward);
leftAction = new MovementAction(kActionLeft, kSpectatorMoveLeft);
rightAction = new MovementAction(kActionRight, kSpectatorMoveRight);
upAction = new MovementAction(kActionUp, kSpectatorMoveUp);
downAction = new MovementAction(kActionDown, kSpectatorMoveDown);

// These register our new actions with the Input Manager.

TheInputMgr->AddAction(forwardAction);
TheInputMgr->AddAction(backwardAction);
TheInputMgr->AddAction(leftAction);
TheInputMgr->AddAction(rightAction);
TheInputMgr->AddAction(upAction);
TheInputMgr->AddAction(downAction);

// Let the Interface Manager determine when to change input devices to gameplay mode.

TheInterfaceMgr->SetInputManagementMode(kInputManagementAutomatic);

// Put the Message Manager in single-player mode.

TheMessageMgr->BeginSinglePlayerGame();

// Create the start window and tell the Interface Manager to display it.

TheInterfaceMgr->AddWidget(new StartWindow);
}

Game::~Game()
{
// When the game DLL is about to be unloaded, this destructor is called.

TheWorldMgr->UnloadWorld();
TheWorldMgr->SetWorldCreator(nullptr);

// If the start window exists, delete it. We need to do this here, instead of letting the
// Interface Manager clean it up, because the destructor code for the window is in this DLL.

delete TheStartWindow;

// Tell the Message Manager to clean up.

TheMessageMgr->EndGame();

delete downAction;
delete upAction;
delete rightAction;
delete leftAction;
delete backwardAction;
delete forwardAction;

// Restore the previous escape key handling function.

TheInputMgr->SetEscapeCallback(prevEscapeCallback, prevEscapeCookie);
}

World *Game::CreateWorld(const char *name, void *cookie)
{
// This function is called when a new world is being loaded. It should
// return a pointer to a newly constructed subclass of the World class.

return (new GameWorld(name));
}

void Game::EscapeCallback(void *cookie)
{
// This function is called when the user hits the escape key in gameplay
// mode because we registered it using the InputMgr::SetEscapeCallback() function.
// In this case, we open the start window shwoing the main menu.

TheInterfaceMgr->AddWidget(new StartWindow);
}
</syntaxhighlight>

== See Also ==

* [[Simple Games]]
* [[SimpleChar Source Code]]

[[Category:Tutorials]]

SimpleBall Source Code - Revision history