Refactor quadtree: Extracted into tfs::map::quadtree namespace with code improvements and tests

[ramon-bernardo]

Pull Request Prelude

• I have adhered to the The Forgotten Server code styling guidelines.
• I have read and understood the contribution guidelines prior to submitting this PR.
• I acknowledge that this PR may be closed if the above criteria are not met.

Changes Proposed:

New namespace

• The Quadtree logic has been extracted from the Map class and relocated to a new namespace: tfs::map::quadtree.

Improved readability

• Added comprehensive code comments and documentation to clarify the purpose and behavior of several functions, including:
  • find_in_range(...)
  • move_creature(...)
  • create_tile(...)
• Additionally, we no longer use inheritance in favor of composition.

Enhanced creature search

• The find_in_range(...) function now utilizes std::experimental::generator for a more efficient search of creatures within a specified range. This update positions the code for future integration with std::generator upon the adoption of C++23.

Tests

• Comprehensive tests have been introduced to verify the functionality of:
  • Creature movement
  • Range-based queries within the quadtree

Note: Tests for tile finding and creation are still pending.

Usage

// Define coordinates and create a new tile.
auto x = 3;
auto y = 3;
auto z = 7;
auto tile = new Tile();
tfs::map::quadtree::create_tile(x, y, z, tile); // Create a tile at (3, 3, 7)

// Create a new creature and add it to the quadtree.
auto creature = new Creature();
tfs::map::quadtree::push_creature(x, y, creature); // Push the creature into the quadtree.

// Find creatures within a specified range and process them.
for (const auto& creature : tfs::map::quadtree::find_in_range(0, 0, 5, 5)) {
    // found creature...
}

// Move the creature to a new location.
tfs::map::quadtree::move_creature(x, y, 6, 6, creature); // Nove the creature from (3, 3) to (6, 6).

// Find creatures again after movement.
for (const auto& creature : tfs::map::quadtree::find_in_range(0, 0, 5, 5)) {
    // nothing...
}
for (const auto& creature : tfs::map::quadtree::find_in_range(6, 6, 10, 10)) {
    // found creature...
}

// Remove the creature from its current location.
tfs::map::quadtree::remove_creature(6, 6, creature); // Remove the creature from (6, 6).

// Check for creatures within the range again after removal.
for (const auto& creature : tfs::map::quadtree::find_in_range(0, 0, 10, 10)) {
    // nothing...
}

[ranisalt]

Can we use Position rather than 3 ints for xyz?

[ramon-bernardo]

Initially, I used pos, but to maintain compatibility with the Map class, I used x, y, and z. I would prefer if Map were also changed to support only Position. See

forgottenserver/src/map.h

Lines 177 to 190 in 2444655

	Tile* getTile(uint16_t x, uint16_t y, uint8_t z) const;
	Tile* getTile(const Position& pos) const { return getTile(pos.x, pos.y, pos.z); }
	/**
	* Set a single tile.
	*/
	void setTile(uint16_t x, uint16_t y, uint8_t z, Tile* newTile);
	void setTile(const Position& pos, Tile* newTile) { setTile(pos.x, pos.y, pos.z, newTile); }
	/**
	* Removes a single tile.
	*/
	void removeTile(uint16_t x, uint16_t y, uint8_t z);
	void removeTile(const Position& pos) { removeTile(pos.x, pos.y, pos.z); }

[ramon-bernardo]

Remove this before merge ;)

[ramon-bernardo]

We could rename the namespace to namespace tfs::map::quadtree and later change the Map class to namespace tfs::map. I think it's a good move, along with namespace tfs::map::astar.

[Zbizu]

suggestion: add extra tree layer for Z coordinate in order to support up to 256 floors

this can still be regulated by MAP_MAX_LAYERS, but would allow otc users to break 16 floors limit more easily

[ramon-bernardo]

@Zbizu I didn't understand your suggestion. Are you proposing to have a configuration for MAP_LAYER? If so, we can do that when we move the Map class to a namespace. ;)

[ramon-bernardo]

Any suggestions for std::generator?