Boid simulation (Julia + GameZero)

This repository contains a small Boids simulation written in Julia using GameZero.jl (render + input loop) and Colors.jl for visuals. The simulation implements the classic three steering behaviors: Separation, Alignment, and Cohesion.

I am currently unable to launch the simulation window ("view mode") on my Windows setup. This README documents the code, the expected behaviour, the minimal tests I ran, observed symptoms and logs, and a clear reproduction recipe so maintainers can diagnose the problem quickly.

---

What the project does

• Spawns n circular agents (boids) with random positions and velocities.

• Each update step computes steering forces for each boid using three rules:

  • Separation: steer away from nearby boids to avoid collisions.
  • Alignment: steer toward the average heading of nearby boids.
  • Cohesion: steer toward the centroid of nearby boids.

• Forces are combined and applied to velocities; positions wrap at borders.

Key tunable parameters in the code:

• perception_radius — how far a boid senses neighbors
• min_speed, max_speed — speed clamping
• separation_dial, alignment_dial, cohesion_dial — influence / smoothing factors

---

Detailed mechanics (how each rule is computed)

All rules are computed for each boid i by scanning neighbors j within perception_radius.

Separation

• For each neighbor j compute the vector from neighbor to self: s = (x_i - x_j, y_i - y_j).
• Sum these vectors across neighbors and divide by total_neighbors to get an average separation vector S.
• The steering contribution is (S - v_i) / separation_dial (rounded/clamped to min_speed..max_speed).
• Purpose: produce a short-range repulsive force proportional to proximity.

Alignment

• Compute the average velocity of neighbors V = mean(v_j).
• Steering = (V - v_i) / alignment_dial (clamped).
• Purpose: gradually steer boid velocity toward local group heading.

Cohesion

• Compute the average position of neighbors C = mean(position_j).
• Steering = (C - position_i - v_i) / cohesion_dial (clamped).
• Purpose: gently pull boids toward the local center of mass.

Final acceleration is the sum of the three steering contributions for each axis; velocities are updated and clamped to min_speed..max_speed.

---

Minimal reproducible examples (what I used to test environment)

Minimal GameZero snippet (testgame.jl)

using GameZero

# define draw in the GameZero namespace so the package picks it up
function GameZero.draw(g::Game)
    background("black")
    circle((200, 200), 50, "red")
end

Expect: running julia testgame.jl from the folder should open a small window with a red circle.

Minimal SDL2 test (sdltest.jl)

using SimpleDirectMediaLayer.LibSDL2

if SDL_Init(SDL_INIT_VIDEO) != 0
    error("SDL_Init Error: ", unsafe_string(SDL_GetError()))
end

window = SDL_CreateWindow("SDL2 test",
    SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
    640, 480,
    SDL_WINDOW_SHOWN)

if window == C_NULL
    error("SDL_CreateWindow Error: ", unsafe_string(SDL_GetError()))
end

SDL_Delay(2000)
SDL_DestroyWindow(window)
SDL_Quit()

Expect: a 640×480 SDL window appears for ~2 seconds and then closes.

---

Observed behaviour on my machine (logs and symptoms)

• Pkg.status("GameZero") reports GameZero v0.3.1 installed in environment.
• Running SimpleDirectMediaLayer.SDL_Init(SimpleDirectMediaLayer.SDL_INIT_VIDEO) returned 0 (SDL video subsystem initialized successfully).
• Running the minimal testgame.jl had no visible window pop up; in REPL it printed Game(#undef, #undef, ... ).
• Attempts to call run() produced MethodError: no method matching run(); the run symbol is shadowed by other packages in my environment (VSCode debug adapter exposes other run methods).
• methods(GameZero.draw) returned zero methods (GameZero saw nothing to call), while methods(draw) in Main showed methods defined there.
• include("...") vs julia testgame.jl differences were tested: running from CMD (julia testgame.jl) exits immediately without opening a window; include in REPL returns method info but no visible window.

I have not been able to get the GameZero event loop to hold and render frames; it appears the package does not call the draw/update loop in my execution path.

---

How to reproduce (exact steps I ran)

1. Clone repo or download files to C:\Users\adrian\Desktop\julia\julia_boid_simulation.

2. In a terminal (PowerShell or CMD):

   cd C:\Users\adrian\Desktop\julia\julia_boid_simulation
   julia testgame.jl

3. Observe: no window created; process returns to prompt with no visible UI.

From the Julia REPL I tried:

cd("C:/Users/adrian/Desktop/julia/julia_boid_simulation")
include("testgame.jl")   # defines draw
Game()                    # constructed object printed as Game(#undef...)

No window appeared.

---

Environment information to include when responding

If you reply to this issue, please include the following in your comment so I can reproduce exactly on my side:

• julia -v
• ] status GameZero (or import Pkg; Pkg.status("GameZero") output)
• ] status SimpleDirectMediaLayer (or Pkg.status("SimpleDirectMediaLayer"))
• OS: Windows 10 build/version
• The exact command you used to run the file (REPL include or CLI julia testgame.jl)
• Full stacktrace if you saw a MethodError or other error in the console

---

Request for assistance (what I need from maintainers / community)

I need help diagnosing why GameZero is not launching its event loop on my Windows 10 machine. Specifically:

• Does GameZero expect GameZero.draw to be defined (module-qualified) or is draw(::Game) in Main sufficient? Which pattern is correct for the current release (please cite the canonical example).
• Is there any known interaction with the VSCode debug adapter or REPL that can block SDL windows from appearing? (I saw run() being shadowed by VSCode's DebugAdapter.)
• Are there additional runtime dependencies (DLLs) or environment variables required on Windows for GameZero / SimpleDirectMediaLayer that are not described in the README?
• If requested, I can provide a small public repo with the exact files and an example Project.toml; please advise what else to include to make reproduction trivial.

Please review the attached minimal repro files and advise next steps, or point to a working minimal example that you have validated on Windows 10.

---

Files included

• testgame.jl — minimal GameZero draw example
• sdltest.jl — minimal SDL2 window test
• boids_full.jl — full boids simulation (original code)

---

Thank you for your time and help. Please comment with pointers, or tag a maintainer if this looks like a bug in GameZero or SimpleDirectMediaLayer on Windows.