Now that our project structure is set up, we can start building the game itself. The first element we need is the ball. This lesson is dedicated to bringing our game's ball to life, from its visual representation to its movement. We will begin by creating a new `Ball` class. This class will use our existing entity-component system to manage its properties. We'll add components for its position, image, and collision bounds. We'll also update our physics component to allow us to disable gravity, which our ball does not need. Our key goals for this lesson are to: - Create a `Ball` entity class. - Add and configure the necessary components. - Modify the engine's `PhysicsComponent` to support custom gravity. - Set an initial velocity to get the ball moving. ## Adding a Ball Class Let's start by adding a class to manage our ball. It'll inherit from our engine's `Entity` class and, like any `Entity`, it needs a reference to the scene it is part of. We'll also give our `Ball` a transform component and image component so we can see it, and we'll position it somewhere near the middle of the scene for now. We'll also save the pointer to the `TransformComponent` as we'll need it later. We'll place this in `Breakout/Ball.h`: ```c++ #pragma once #include "Engine/ECS/Entity.h" #include "Engine/ECS/ImageComponent.h" #include "Engine/ECS/TransformComponent.h" #include "Breakout/BreakoutScene.h" class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { Transform = AddComponent(); Transform->SetPosition({ 6.f * Scene::PIXELS_PER_METER, 6.f * Scene::PIXELS_PER_METER }); AddComponent("Assets/Grey.png"); } private: TransformComponent* Transform; }; ``` Let's add a `Ball` to our scene. Loading levels will be quite a complex process eventually, especially once we start deserializing data from our editor files. So, let's proactively break it out into a standalone function called `Load()`, which will take the level we want to load as an argument. From our constructor, we'll `Load()` level 1: ```c++ #pragma once #include #include "Engine/Scene.h" class BreakoutScene : public Scene { public: BreakoutScene(Window& ParentWindow) : Scene{ParentWindow} { Load(1);// } void Load(int Level);// }; ``` We'll implement `Load()` in a new source file, `BreakoutScene.cpp`. As a reminder, the entities of our scene are stored in a `std::vector` called `Entities`, which our `BreakoutScene` is inheriting from the base `Scene` class in our engine. Every time we call `Load()`, we will clear all the entities in the scene, and load our new set of entities. For now, the only thing we have to load is our `Ball`: ```c++ #include "Breakout/BreakoutScene.h" #include "Breakout/Ball.h" void BreakoutScene::Load(int Level) { Entities.clear(); Entities.emplace_back( std::make_unique(*this) ); } ``` Remember to add this file in a way that the compiler is aware of it. For example, if you're using CMake, you'll need to update our `CMakeLists.txt` to include this new source file: ```plain text # # ... add_executable(Breakout "main.cpp" # ... "Breakout/src/BreakoutScene.cpp"# # We'll add this later # "Breakout/src/Ball.cpp" ) ``` With these changes, we should now see our ball rendered in the scene: A screenshot of the ball rendered in the scene

A screenshot of the ball rendered in the scene

### Configuring Size and Colliders For our ball to bounce around and collide with things, we need to give it a collider. Let's add a `CollisionComponent`, and save a pointer to this component as a member variable as we'll need it later. We also need to set the size of the collider to be around the same size as the ball using the `SetSize()` method. In our example, the correct size seems to be a width of around `1.1` and a height of `1.7` world units, but yours may be different: ```c++ #pragma once #include "Engine/ECS/Entity.h" #include "Engine/ECS/ImageComponent.h" #include "Engine/ECS/TransformComponent.h" #include "Engine/ECS/CollisionComponent.h"// #include "Breakout/BreakoutScene.h" class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { Transform = AddComponent(); Transform->SetPosition({ 6.f * Scene::PIXELS_PER_METER, 6.f * Scene::PIXELS_PER_METER }); Collision = AddComponent();// Collision->SetSize(// 1.2f * Scene::PIXELS_PER_METER,// 1.2f * Scene::PIXELS_PER_METER// );// AddComponent("Assets/Grey.png"); } private: TransformComponent* Transform; CollisionComponent* Collision;// }; ``` Remember, if you enable the `DRAW_DEBUG_HELPERS` preprocessor definition in `CMakeLists.txt` (or your build configuration), the collider will draw a yellow rectangle showing its position and size: A screenshot of the ball rendered in the scene with debug helpers drawn

A screenshot of the ball rendered in the scene with debug helpers drawn

If you also need to change the position of the collider relative to the image, you can use the `SetOffset()` method on the `CollisionComponent`. Our ball is too large at the minute, so we'll also use the `SetScale()` method on the transform component to scale it down. We'll also update the starting position to near the bottom of the scene, with enough space to put the paddle underneath it in the future: ```c++ // ... class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { Transform = AddComponent(); Transform->SetPosition({ 6.f * Scene::PIXELS_PER_METER, 6.f * Scene::PIXELS_PER_METER }); Transform->SetScale(0.3f);// Collision = AddComponent(); Collision->SetSize( 1.2f * Scene::PIXELS_PER_METER, 1.2f * Scene::PIXELS_PER_METER ); AddComponent("Assets/Grey.png"); } // ... }; ``` A screenshot of the ball rendered at the correct size and position

A screenshot of the ball rendered at the correct size and position

## Disabling Gravity To get our ball moving, we can add a `PhysicsComponent`, but we need to make a small enhancement to it first. Our `PhysicsComponent` assumes we always want to simulate gravity, but that's not the case in our Breakout game. The effect of gravity is currently controlled by `Scene::GRAVITY`, which we could update in our `Scene` class, or in our `BreakoutScene` constructor. However, another option would be to update our `PhysicsComponent` to make gravity optional. This gives us more flexibility, as it allows us to configure gravity on a per-entity basis, rather than for the entire scene. Let's update the component with a new `Vec2` member to store the desired gravity for this specific component instance, as well as a getter and setter to access it. We'll use the scene's gravity by default: ```c++ // ... #include "Engine/Scene.h"// class PhysicsComponent : public Component { public: // ... Vec2 GetGravity() const { return Gravity; }// void SetGravity(Vec2 NewGravity) {// Gravity = NewGravity;// }// private: // ... Vec2 Gravity{Scene::GRAVITY}; // }; ``` In the physics component's `Tick()` function, we can now use this member variable instead of applying the global `Scene::GRAVITY`. ```c++ // ... void PhysicsComponent::Tick(float DeltaTime) { ApplyForce(Scene::GRAVITY * Mass);// ApplyForce(Gravity * Mass);// Velocity += Acceleration * DeltaTime; SetOwnerPosition( GetOwnerPosition() + Velocity * DeltaTime ); Acceleration = {0.0, 0.0}; } // ... ``` ## Adding Movement Now that we can control gravity, let's add a `PhysicsComponent` to our `Ball`, and disable the effects of gravity by setting it to `{0, 0}`. We'll also need to use our physics component in other `Ball` methods in the future, so we'll store its pointer as a member variable: ```c++ // ... #include "Engine/ECS/PhysicsComponent.h"// class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { // ... Physics = AddComponent();// Physics->SetGravity({0.f, 0.f});// AddComponent("Assets/Grey.png"); } private: // ... PhysicsComponent* Physics;// }; ```

### Tick Order The order in which we add components to our entity influences the order in which those components will tick. This sometimes affects the behavior of our program in subtle ways. For example, the physics component updates the object's position, and the image component uses the object's position to decide where to render. As such, if we add the image component _**after**_ the physics component, that means the image component's tick function will be using the latest positional data, which is what we want. If the image component ticked before the physics component, it would be using the position data from the previous frame. This is rarely noticeable and sometimes not worth worrying about, but reordering the insertion order of our components is pretty easy, so we may as well be mindful of it. Specifically: - `InputComponent::Tick()` updates the physics component's `Velocity`, and `PhysicsComponent::Tick()` uses that `Velocity`. Therefore, input components should be added _**before**_ the physics component. - `PhysicsComponent::Tick()` updates the transform component's position, and `ImageComponent::Tick()` and `CollisionComponent::Tick()` use that position. Therefore, image and collision components should be added _**after**_ the physics component.

To get our ball moving, let's first add a configuration variable that lets us easily change the speed in the future. We'll add this to our `Config.h` file within a new `Config::Breakout` namespace: ```c++ // ... namespace Config::Breakout {// // Meters per second// inline const float BALL_SPEED{10.f};// }// // ... ``` Back in our `Ball` class, we can set the velocity in three steps: 1. We'll create a vector to set the initial direction of our ball. You can use any value you prefer here - we'll use `{1, -2}`, meaning the ball will initially move to the right (positive x) and up (negative y). 2. We'll normalize this vector using `.Normalize()`, returning a vector with the same direction but with a length of `1`. 3. We'll multiply this normalized vector by the `BALL_SPEED` configuration value, to give our velocity in meters per second 4. We'll multiply this by our pixels-per-meter coefficient, to give us a final velocity in pixels per second Example of normalizing a vector

These steps ensure our velocity matches both the direction `{1, -2}` and speed `10` that we configured. ```c++ // ... #include "Config.h"// #include "Engine/Vec2.h"// class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { // ... Physics = AddComponent(); Physics->SetGravity({0, 0}); Physics->SetVelocity(// Vec2{1.f, -2.f}.Normalize()// * Config::Breakout::BALL_SPEED// * Scene::PIXELS_PER_METER// );// // The colliwion component comes after the // physics component to ensure it picks // up the movement from this frame Collision = AddComponent(); Collision->SetSize( 1.2f * Scene::PIXELS_PER_METER, 1.2f * Scene::PIXELS_PER_METER ); AddComponent("Assets/Grey.png"); } private: TransformComponent* Transform; PhysicsComponent* Physics; CollisionComponent* Collision; }; ``` With those changes, our ball should now start moving, eventually leaving our screen entirely. If we enable `DRAW_DEBUG_HELPERS`, our `PhysicsComponent` will draw our movement trajectories as blue lines: A screenshot of the ball moving

In the next part, we'll add some walls around the edges of the window that our ball will bounce off. ## Complete Code Complete versions of the files we updated in this section are available below: ```c++ #include "Breakout/BreakoutScene.h" #include "Breakout/Ball.h" void BreakoutScene::Load(int Level) { Entities.clear(); Entities.emplace_back( std::make_unique(*this) ); } ``` ```c++ #pragma once #include "Config.h" #include "Engine/Vec2.h" #include "Engine/ECS/Entity.h" #include "Engine/ECS/ImageComponent.h" #include "Engine/ECS/TransformComponent.h" #include "Engine/ECS/CollisionComponent.h" #include "Engine/ECS/PhysicsComponent.h" #include "Breakout/BreakoutScene.h" class Ball : public Entity { public: Ball(BreakoutScene& Scene) : Entity{Scene} { Transform = AddComponent(); Transform->SetPosition({ 6.f * Scene::PIXELS_PER_METER, 6.f * Scene::PIXELS_PER_METER }); Transform->SetScale(0.5f); Physics = AddComponent(); Physics->SetGravity({0.f, 0.f}); Physics->SetVelocity( Vec2{1.f, -2.f}.Normalize() * Config::Breakout::BALL_SPEED * Scene::PIXELS_PER_METER ); Collision = AddComponent(); Collision->SetSize( 1.2f * Scene::PIXELS_PER_METER, 1.2f * Scene::PIXELS_PER_METER ); AddComponent("Assets/Grey.png"); } private: TransformComponent* Transform; CollisionComponent* Collision; PhysicsComponent* Physics; }; ``` ```c++ #pragma once #include #include "Engine/Scene.h" class BreakoutScene : public Scene { public: BreakoutScene(Window& ParentWindow) : Scene{ParentWindow} { Load(1); } void Load(int Level); }; ``` ```c++ #include #include "Engine/ECS/Entity.h" #include "Engine/ECS/PhysicsComponent.h" #include "Engine/ECS/TransformComponent.h" #include "Engine/Scene.h" #include "Engine/Utilities.h" void PhysicsComponent::Initialize() { if (!GetOwner()->GetComponent()) { std::cerr << "Error: PhysicsComponent " "requires TransformComponent on its Owner\n"; GetOwner()->RemoveComponent(this); } } void PhysicsComponent::SetMass(float NewMass) { if (NewMass <= 0.0) { std::cerr << "Error: Mass must be positive. " "Setting to 1.0kg instead\n"; Mass = 1.0; } else { Mass = NewMass; } } void PhysicsComponent::ApplyForce( const Vec2& Force ) { if (Mass > 0.0f) { Acceleration += Force / Mass; } } void PhysicsComponent::ApplyImpulse( const Vec2& Impulse ) { if (Mass > 0.0f) { Velocity += Impulse / Mass; } } void PhysicsComponent::Tick(float DeltaTime) { ApplyForce(Gravity * Mass); Velocity += Acceleration * DeltaTime; SetOwnerPosition( GetOwnerPosition() + Velocity * DeltaTime ); Acceleration = {0.0, 0.0}; } void PhysicsComponent::DrawDebugHelpers( SDL_Surface* Surface ) { #ifdef DRAW_DEBUG_HELPERS auto [x, y]{GetOwnerPosition()}; SDL_Rect PositionIndicator{ int(x) - 2, int(y) - 2, 4, 4 }; SDL_FillSurfaceRect( GetScene().Trajectories, &PositionIndicator, SDL_MapRGB( SDL_GetPixelFormatDetails( GetScene().Trajectories->format ), nullptr, 0, 0, 255 ) ); #endif } ``` ```c++ #pragma once #include "Engine/ECS/Component.h" #include "Engine/Vec2.h" #include "Engine/Scene.h" class PhysicsComponent : public Component { public: using Component::Component; void Initialize() override; void Tick(float DeltaTime) override; void DrawDebugHelpers(SDL_Surface* Surface) override; void ApplyForce(const Vec2& Force); void ApplyImpulse(const Vec2& Impulse); Vec2 GetVelocity() const { return Velocity; } void SetVelocity(const Vec2& NewVelocity) { Velocity = NewVelocity; } Vec2 GetGravity() const { return Gravity; } void SetGravity(Vec2 NewGravity) { Gravity = NewGravity; } float GetMass() const { return Mass; } void SetMass(float NewMass); private: Vec2 Velocity{0.0, 0.0}; // m/s Vec2 Gravity{Scene::GRAVITY}; // m/s^2 Vec2 Acceleration{0.0, 0.0}; // m/s^2 float Mass{1.0}; // kg }; ``` ```c++ #pragma once #include #include #include #include namespace UserEvents{ #ifdef WITH_EDITOR inline Uint32 ACTOR_DRAG{SDL_RegisterEvents(1)}; inline Uint32 LOAD_LEVEL{SDL_RegisterEvents(1)}; inline Uint32 SAVE_LEVEL{SDL_RegisterEvents(1)}; inline Uint32 SAVE_AND_PLAY_LEVEL{SDL_RegisterEvents(1)}; inline Uint32 LEVEL_EDIT{SDL_RegisterEvents(1)}; #endif inline Uint32 LAUNCH_LEVEL{SDL_RegisterEvents(1)}; } namespace Config { enum class ActorType : Uint8 { Actor = 0, BlueBlock = 1, GreenBlock = 2, CyanBlock = 3, OrangeBlock = 4, RedBlock = 5, YellowBlock = 6, }; inline const std::vector BUTTON_COLORS{ SDL_Color{15, 15, 15, 255}, // Normal SDL_Color{15, 155, 15, 255}, // Hover SDL_Color{225, 15, 15, 255}, // Active SDL_Color{60, 60, 60, 255} // Disabled }; inline constexpr SDL_Color FONT_COLOR{ 255, 255, 255, 255 }; inline const std::string BASE_PATH{ SDL_GetBasePath() }; inline const std::string FONT{ BASE_PATH + "Assets/Rubik-SemiBold.ttf" }; } #ifdef WITH_EDITOR namespace Config::Editor { inline const Uint8 VERSION{1}; // Level inline const int HORIZONTAL_GRID_SNAP{50}; inline const int VERTICAL_GRID_SNAP{25}; inline const Uint8 GRID_WIDTH{13}; inline const Uint8 GRID_HEIGHT{6}; inline const int LEVEL_WIDTH{ HORIZONTAL_GRID_SNAP * GRID_WIDTH }; inline const int LEVEL_HEIGHT{ VERTICAL_GRID_SNAP * GRID_HEIGHT }; inline constexpr SDL_Color LEVEL_BACKGROUND{ 50, 50, 50, 255 }; // ActorMenu inline const int ACTOR_MENU_WIDTH{70}; inline const int ACTOR_MENU_POSITION_X{LEVEL_WIDTH}; inline const SDL_Color ACTOR_MENU_BACKGROUND{ 15, 15, 15, 255 }; inline const int PADDING{10}; // Window inline const std::string WINDOW_TITLE{"Editor"}; inline const int WINDOW_WIDTH{ LEVEL_WIDTH + ACTOR_MENU_WIDTH }; inline const int WINDOW_HEIGHT{LEVEL_HEIGHT + 50}; inline const SDL_Color WINDOW_BACKGROUND{ 35, 35, 35, 255 }; } #endif namespace Config::Engine { inline const std::string WINDOW_TITLE{"Breakout"}; inline const int WINDOW_WIDTH{720}; inline const int WINDOW_HEIGHT{400}; inline const SDL_Color WINDOW_BACKGROUND{ 35, 35, 35, 255 }; } namespace Config::Breakout { inline const float BALL_SPEED{10}; } inline void CheckSDLError(const std::string& Msg) { #ifdef CHECK_ERRORS const char* error = SDL_GetError(); if (*error != '\0') { std::cerr << Msg << " Error: " << error << '\n'; SDL_ClearError(); } #endif } ``` ```plain text # cmake_minimum_required(VERSION 3.16) set(CMAKE_CXX_STANDARD 20) project(Breakout VERSION 1.0.0) add_executable(Breakout "main.cpp" "Editor/src/Button.cpp" "Editor/src/Blocks.cpp" "Editor/src/Actor.cpp" "Editor/src/ActorTooltip.cpp" "Editor/src/Level.cpp" "Engine/src/Scene.cpp" "Engine/ECS/src/Component.cpp" "Engine/ECS/src/CollisionComponent.cpp" "Engine/ECS/src/ImageComponent.cpp" "Engine/ECS/src/PhysicsComponent.cpp" "Engine/ECS/src/InputComponent.cpp" "Engine/ECS/src/Commands.cpp" "Breakout/src/BreakoutScene.cpp" # We'll add this later # "Breakout/src/Ball.cpp" ) target_compile_definitions( Breakout PUBLIC WITH_EDITOR CHECK_ERRORS # We'll use these later # DRAW_DEBUG_HELPERS # ENABLE_CHEATS ) target_include_directories( Breakout PUBLIC ${PROJECT_SOURCE_DIR} ) set(SDLTTF_VENDORED ON) set(VENDOR_DIR "${PROJECT_SOURCE_DIR}/vendor") add_subdirectory(${VENDOR_DIR}/SDL) add_subdirectory(${VENDOR_DIR}/SDL_image) add_subdirectory(${VENDOR_DIR}/SDL_ttf) target_link_libraries(Breakout PRIVATE SDL3::SDL3 SDL3_image::SDL3_image SDL3_ttf::SDL3_ttf ) set(AssetDirectory "${PROJECT_SOURCE_DIR}/Assets") add_custom_command( TARGET Breakout POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different "$" "$" "$" "$" COMMAND ${CMAKE_COMMAND} -E copy_directory_if_different "${AssetDirectory}" "$/Assets" VERBATIM ) ``` ## Summary In this lesson, we successfully added the first interactive element to our Breakout game: the ball. We created a dedicated `Ball` class, equipped it with transform, image, collision, and physics components, and set it in motion. We also enhanced our engine's `PhysicsComponent` to allow for per-entity gravity customization. Here are the key takeaways: - Game-specific objects are created as `Entity` subclasses that compose generic components. - The order in which components are added can affect behavior, particularly between physics, collision, and rendering. - It's often necessary to adapt or enhance generic engine features (like gravity in `PhysicsComponent`) to suit the specific needs of a game. - Vector normalization is a useful technique for setting an object's velocity, allowing us to define a direction and speed independently.

Breakout: The Ball

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation