Grid-Based Placement

Our first step towards a grid-based system is configuring the grid itself. In Config.h, inside the Config::Editor namespace, we'll add constants defining the snapping distances. HORIZONTAL_GRID_SNAP will be 50, and VERTICAL_GRID_SNAP will be 25, reflecting the dimensions of our game's blocks.

We also need to define how many grid cells make up our level. Let's add GRID_WIDTH and GRID_HEIGHT. We'll set them to 13 and 6 for our examples, but our program will scale to any values we prefer here.

We'll use the Uint8 type for these. This is an 8-bit unsigned integer, meaning it can hold values from 0 to 255. Using a fixed-size type like Uint8 is important because we intend to serialize these dimensions to a file later; it ensures the data size is predictable. If we needed larger levels, Uint16 would be the next choice.

We'll also update the level's rendering size - LEVEL_WIDTH and LEVEL_HEIGHT - to be based on these new values. This ensures that the level's rendering area in the editor always matches the space required by the defined grid. Any changes to the grid configuration (number of cells or snap size) will automatically propagate to the level's dimensions.

1// Config.h
2// ...
3
4#ifdef WITH_EDITOR
5namespace Config::Editor {
6// Level
7inline const int HORIZONTAL_GRID_SNAP{50};
8inline const int VERTICAL_GRID_SNAP{25};
9inline const Uint8 GRID_WIDTH{13};
10inline const Uint8 GRID_HEIGHT{6};
11inline const int LEVEL_WIDTH{
12  HORIZONTAL_GRID_SNAP * GRID_WIDTH};
13inline const int LEVEL_HEIGHT{
14  VERTICAL_GRID_SNAP * GRID_HEIGHT};
15inline constexpr SDL_Color LEVEL_BACKGROUND{
16  50, 50, 50, 255};
17
18// ...
19}
20// ...
21#endif

Now that we have the grid dimensions configured, we need a function within our Level class to perform the actual snapping calculation. This function will take an arbitrary coordinate (x, y) and return the coordinates of the top-left corner of the grid cell that contains it.

Let's declare this function in Editor/Level.h. We'll add a public member function SnapToGridPosition() that accepts two int parameters (x and y) and returns an SDL_Point, which holds the resulting snapped x and y coordinates.

1// Editor/Level.h
2// ...
3
4namespace Editor {
5 // ...
6
7class Level {
8 public:
9  // ...
10  SDL_Point SnapToGridPosition(int x, int y);
11  // ...
12};
13}

Now let's implement SnapToGridPosition() in Editor/Source/Level.cpp.

The logic relies on integer division. When we divide the input coordinate (e.g., x) by the corresponding grid snap size (sx), integer division automatically truncates any remainder, effectively rounding down to the nearest whole number of grid steps.

Multiplying this result back by the snap size (sx) gives us the coordinate of the grid line just below or at the input coordinate. We do this for both x and y using HORIZONTAL_GRID_SNAP and VERTICAL_GRID_SNAP from our configuration, and return the result as an SDL_Point.

1// Editor/Source/Level.cpp
2// ...
3
4SDL_Point Level::SnapToGridPosition(
5  int x, int y
6) {
7  using namespace Config::Editor;
8  int sx{HORIZONTAL_GRID_SNAP};
9  int sy{VERTICAL_GRID_SNAP};
10  return {
11    (x / sx) * sx,
12    (y / sy) * sy,
13  };
14}

Now that our Level can calculate snapped positions, let's apply this to the ActorTooltip. We want the tooltip to snap to the grid, but only when the mouse cursor is actually hovering over the level area. When the cursor is outside the level (e.g., over the actor menu or elsewhere on the screen entirely), the tooltip should follow the mouse smoothly as before.

We can achieve this conditional behavior in ActorTooltip::PositionWindow(). We already have an if statement checking ParentScene.GetLevel().HasMouseFocus().

The logic for smooth, non-snapped positioning (using the DragOffset) belongs in the else block - the case where the mouse is not over the level.

Let's refactor the code. We'll move the lines that calculate the position using DragOffset and the corresponding SDL_SetWindowPosition() call inside the else block.

1// Editor/Source/ActorTooltip.cpp
2// ...
3
4void ActorTooltip::PositionWindow() {
5  int x, y;
6  SDL_GetGlobalMouseState(&x, &y);
7  
8  auto [DragOffsetX, DragOffsetY]{
9    DragActor->GetDragOffset()
10  };
11
12  SDL_SetWindowPosition(
13    SDLWindow,
14    x - DragOffsetX,
15    y - DragOffsetY
16  );
17
18  if (ParentScene.GetLevel().HasMouseFocus()) {
19    SDL_SetWindowOpacity(SDLWindow, 1);
20    SDL_SetCursor(SDL_GetDefaultCursor());
21  } else {
22    auto [DragOffsetX, DragOffsetY]{
23      DragActor->GetDragOffset()
24    };
25
26    SDL_SetWindowPosition(
27      SDLWindow,
28      x - DragOffsetX,
29      y - DragOffsetY
30    );
31    SDL_SetWindowOpacity(SDLWindow, 0.5);
32    SDL_SetCursor(DenyCursor);
33  }
34}

Now, let's add the code to the if block for when the tooltip should snap. We face a slight complication: the tooltip's position is set using global screen coordinates - SDL_SetWindowPosition() - but our SnapToGridPosition() function works with coordinates relative to the level area within our main window.

To bridge this, we first need the screen coordinates of our main window's top-left corner. We can get this from the ParentScene, storing the result in WinX and WinY.

Next, we calculate the mouse's position relative to this window by subtracting WinX and WinY from the global mouse coordinates (x, y). We pass these relative coordinates (x - WinX, y - WinY) to SnapToGridPosition().

This gets what the grid-snapped tooltip position would be if our main window was positioned at (0, 0) within the overall screen. We'll store those values at GridX, GridY.

However, our main window is unlikely to be positioned at (0, 0) so, when setting the final position of our tooltip, we need to add the window's actual position back to our final result. So, we call SDL_SetWindowPosition() , passing WinX + GridX and WinY + GridY.

1// Editor/Source/ActorTooltip.cpp
2// ...
3
4void ActorTooltip::PositionWindow() {
5  int x, y;
6  SDL_GetGlobalMouseState(&x, &y);
7
8  if (ParentScene.GetLevel().HasMouseFocus()) {
9    SDL_SetWindowOpacity(SDLWindow, 1);
10    SDL_SetCursor(SDL_GetDefaultCursor());
11    auto [WinX, WinY]{
12      ParentScene.GetWindow().GetPosition()
13    };
14
15    auto [GridX, GridY]{
16      ParentScene.GetLevel().SnapToGridPosition(
17        x - WinX, y - WinY
18      )
19    };
20
21    SDL_SetWindowPosition(
22      SDLWindow, WinX + GridX, WinY + GridY
23    );
24  } else {
Else Block Unchanged|Show
35  }
36}

Don't worry if this transformation between coordinate systems doesn't entirely make sense at this point. We have dedicated lessons on coordinate systems, and transformations between them, coming later in the course.

If we run our program now, we should see our tooltip snapping to grid positions as we drag our actor over the level. However, once we drop the actor, its position in the level is not snapped to that same grid, so let's address that next.

Snapping Actors to the Grid

Our final step for snapping is to ensure the actors themselves land on the grid coordinates when dropped. This requires updating the Level::HandleDrop() function.

We previously used the mouse position and a drag offset to determine the drop location. Now, we want to ignore the drag offset and use only the snapped grid position.

We'll modify HandleDrop() to delete the code that gets DragOffset. After getting the window-relative MouseX and MouseY, we'll call SnapToGridPosition() to calculate GridX and GridY.

We'll then update both SetPosition() calls (inside the if for cloned actors and the else for moved actors) to use GridX, GridY as the target coordinates.

1// Editor/Source/Level.cpp
2// ...
3
4void Level::HandleDrop(Actor* DragActor) {
5  DragActor->SetIsVisible(true);
6  if (!HasMouseFocus()) {
7    return;
8  }
9
10  int MouseX, MouseY;
11  SDL_GetMouseState(&MouseX, &MouseY);
12  auto [GridX, GridY]{
13    SnapToGridPosition(
14      MouseX, MouseY
15    )
16  };
17
18  using enum ActorLocation;
19  if (DragActor->GetLocation() == Menu) {
20    ActorPtr NewActor{DragActor->Clone()};
21    NewActor->SetPosition(GridX, GridY);
22    SelectedActor = NewActor.get();
23    AddToLevel(std::move(NewActor));
24  } else {
25    DragActor->SetPosition(GridX, GridY);
26    SelectedActor = DragActor;
27  }
28}
29
30void Level::AddToLevel(ActorPtr NewActor) {
31  NewActor->SetLocation(ActorLocation::Level);
32  Actors.push_back(std::move(NewActor));
33}
34
35bool Level::HasMouseFocus() const {
36  if (!ParentScene.HasMouseFocus()) {
37    return false;
38  }
39  int x, y;
40  SDL_GetGlobalMouseState(&x, &y);
41  auto [WinX, WinY]{
42    ParentScene.GetWindow().GetPosition()
43  };
44
45  if (
46    x >= WinX + Config::Editor::LEVEL_WIDTH ||
47    y >= WinY + Config::Editor::LEVEL_HEIGHT
48  ) {
49    return false;
50  }
51  return true;
52}
53
54SDL_Point Level::SnapToGridPosition(
55  int x, int y
56) {
57  using namespace Config::Editor;
58  int sx{HORIZONTAL_GRID_SNAP};
59  int sy{VERTICAL_GRID_SNAP};
60  return {
61    (x / sx) * sx,
62    (y / sy) * sy,
63  };
64}

Running our program, we should now see we can easily position our actors in an organized grid:

One Actor Per Grid Position

Our editor now snaps actors to a grid, but it still allows multiple actors to occupy the same grid cell. For many tile or grid-based games, this is undesirable; each cell should hold at most one actor. We need to enforce this constraint.

The desired behavior is: when an actor is dropped onto a grid cell, any actor already present in that cell should be removed first. However, if the user simply clicks an actor and releases (effectively dropping it back into its original cell), we shouldn't delete and replace it.

To implement this, we'll add a helper function to the Level class specifically for deleting an actor at a given grid position, with an exception for the actor being dropped.

Let's declare DeleteAtPosition() in the public section of Editor/Level.h. The Unless parameter will hold a pointer to the actor currently being dragged/dropped, preventing it from deleting itself if dropped in its own previous location.

1// Editor/Level.h
2// ...
3
4namespace Editor {
5// ...
6
7class Level {
8 public:
9  // ...
10  void DeleteAtPosition(
11    int x, int y, const Actor* Unless);
12  // ...
13};
14}

Now, let's implement DeleteAtPosition() in Editor/Source/Level.cpp. We need to search through our Actors vector to find if any actor's position matches the provided x and y.

We can use a traditional for loop with an index. Inside the loop, we'll get the position (ax, ay) of the current actor Actors[i]. We'll check if ax == x and ay == y. We'll check if the raw pointer Actors[i].get() is not equal to the Unless pointer.

If all conditions are true, we've found a different actor at the target location that needs to be removed. We use Actors.erase() to remove it and immediately break from the loop, as there can be at most one actor per position now.

1// Editor/Source/Level.cpp
2// ...
3
4void Level::DeleteAtPosition(
5  int x, int y, const Actor* Unless
6) {
7  for (size_t i{0}; i < Actors.size(); ++i) {
8    auto [ax, ay]{Actors[i]->GetPosition()};
9    if (ax == x && ay == y
10        && Actors[i].get() != Unless
11    ) {
12      Actors.erase(Actors.begin() + i);
13      break;
14    }
15  }
16}

Finally, we integrate the deletion logic into the drop handling process. In Level::HandleDrop(), right after calculating the target grid coordinates GridX, GridY, we need to call our new deletion function.

We'll add our call to DeleteAtPosition() to ensure that, before we either clone DragActor to (GridX, GridY) or move DragActor to (GridX, GridY), any other actor currently occupying that cell is removed.

The DragActor pointer is passed as the Unless argument, preventing self-deletion when moving an actor back to its original cell or just clicking it.

1// Editor/Source/Level.cpp
2// ...
3
4void Level::HandleDrop(Actor* DragActor) {
5  DragActor->SetIsVisible(true);
6  if (!HasMouseFocus()) {
7    return;
8  }
9
10  int MouseX, MouseY;
11  SDL_GetMouseState(&MouseX, &MouseY);
12  auto [GridX, GridY]{
13    SnapToGridPosition(
14      MouseX,
15      MouseY
16    )
17  };
18  DeleteAtPosition(GridX, GridY, DragActor);
19  
Remaining Code (Unchanged)|Show
30}

If we compile and run our program, we should now verify that, when we drop an actor into a grid position, any other actor that was previously in that grid position gets replaced.

Complete Code

Our updated Level class and Config.h file are provided below:

Config.h

Editor/Level.h

Editor/Source/Level.cpp

We also updated the PositionWindow() function of our ActorTooltip:

Editor/Source/ActorTooltip.cpp

Summary

This lesson transitioned our level editor from freeform placement to a structured grid-based system. We implemented grid snapping for precise alignment and enforced a rule allowing only one actor per grid cell, replacing any existing actor upon dropping a new one.

Key steps:

• Defined grid parameters in configuration.
• Used fixed-width integers (Uint8) for grid dimensions to prepare for serialization.
• Implemented a SnapToGridPosition() function using integer division math: $(\text{coord} / \text{snap}) \times \text{snap}$.
• Updated ActorTooltip::PositionWindow() to handle coordinate space conversions (global mouse -> window relative -> snapped -> window relative -> screen) for snapped tooltip positioning over the level.
• Modified Level::HandleDrop() to use snapped coordinates and ignore the drag offset.
• Added Level::DeleteAtPosition() to remove existing actors from a target cell before placing a new one.
• Integrated the deletion call into HandleDrop() to enforce single occupancy per cell.