GameMaker Hybrid 2D Agent System

A modular, highly decoupled pathfinding and agent management system built in GameMaker.

This system solves the complex problem of mixing strict grid-based environments (like factory builders or colony sims) with fluid, multi-unit swarm movement (like traditional RTS games).

🌟 Key Features

• Dual-Mode Architecture: * ROUTE Mode: Strict matrix reservation. Agents lock tiles ahead of them, wait in traffic, and prevent overlaps. Ideal for factory logistics and predictable NPC routines.
  • RTS Mode: Fluid movement. Agents decouple from the grid matrix during travel, using pixel-perfect path following and soft collisions, anchoring back to the grid only upon arrival.
• Ulam Spiral Formations: Dynamically calculates valid, non-overlapping destination tiles for multiple agents around a single target click.
• Swarm Flow (Boids): Uses separation vectors to push agents away from each other during RTS travel. This prevents the classic A* "single-file funneling" effect when rounding corners.
• Waypoint Relaxation: Agents take smoother, wider turns at intermediate waypoints to maintain swarm cohesion without fighting for the exact same pixel.

🏗️ Architecture & Core Objects

The system is split into five main components, making it entirely plug-and-play for your existing project:

1. obj_grid_manager (The Map Brain)

Holds global.matrix (a 2D array representing the physical occupation of the room) and handles the request_reservation and free_reservation functions. This ensures two agents can never legally occupy the same final tile.

2. obj_input_manager (The RTS Commander)

Handles box-selection (Shift + Click) and raycasting. When ordering multiple units, it generates a mathematical spiral outward from the click, checks mp_grid for walls/obstacles, and assigns the closest available parking spot to each selected agent.

3. obj_agent (The Unit Brain)

A Finite State Machine (IDLE, MOVING, WAITING) powered by a Belief-Desire-Intention (BDI) queue.

• Navigation: It uses GameMaker's native mp_grid_path to generate a macro-route (avoiding walls) but extracts the exact pixel coordinates to travel smoothly.
• Rendering: Features built-in Y-Sorting (depth = -bbox_bottom) and visual offsets so sprites can be adjusted without breaking the physical A* collision center.

4. obj_route_starter (The Route Generator)

Acts as a physical waypoint and route compiler on the map. It let's the user create paths by clicking on it and drawing arrows. When an agent stop over this object (enters the IDLE state), it automatically downloads the route into its intention queue and begins executing it step-by-step.

5. obj_Obstacle (The Static Environment)

A smart, plug-and-play parent object for buildings, trees, and walls.

• Auto-Sizing: It automatically calculates its own grid footprint based on its tiled_size_x and tiled_size_y variables.
• Auto-Registration: It registers itself into both global.matrix and mp_grid upon creation, and cleanly frees those cells if it is destroyed.

🎮 How to Use

RTS Controls (Swarm Movement)

• Select Agents: Hold Shift + Left Click & Drag to create a selection box around multiple agents.
• Cancel Selection: Hold Shift + Left Click to clear your current selection.
• Move Agents: With agents selected, click on the map to issue a move command. They will automatically calculate a path and form around the target using the Ulam Spiral logic.

Route Controls (Grid Automation)

• Create a Route: Left Click on an obj_route_starter (Router) to begin placing directional arrows and drawing a path on the grid.
• Confirm Route: Press Enter to compile and save the route. Any agent that stops over this Router will now automatically follow the established path.

🚀 How to Implement

1. Initialize the system by calling the Start_world() function (just put the obj_start_world in your room). Make sure this runs first in your execution order (this function automatically creates the obj_input_manager, obj_grid_manager and sets up the environment).
2. Ensure your room's floor tiles align perfectly with global.tile_size.
3. Create static colliders by assigning obj_Obstacle as the parent to your environment sprites. Be sure to set their tiled_size_x and tiled_size_y variables to match the sprite's dimensions.
4. Place obj_route_starter objects on the map to define automated paths.
5. Drop your obj_agent instances into the room.
6. Have fun!

🤝 Contributing

This project is open-source. If you find ways to optimize the vector math, improve the Boids alignment/cohesion, or add new mechanics, please feel free to contribute to the repo.

Let's build something cool together!