Cortex Bot

Cortex Bot is a Quake (1996) deathmatch bot with human-like combat, navigation, and resource-management behavior. It compiles to progs.dat via fteqcc and can run standalone or be wired into an existing mod.

Highlights

• Smart combat: weapon selection favors range and ammo, dodges rockets, leads targets, and retreats when outmatched.
• Advanced movement: uses whisker sensors, platform riding, rocket jumps, water handling, teleporters, and gap jumping to stay mobile.
• Resource tracking: watches item pickups, major power-up respawns, and prioritizes health, armor, and ammunition.
• Sound & state awareness: reacts to combat noises, keeps a hunting state machine, and exposes well-documented bot entity fields.

Quick start

1. Install fteqcc from https://www.fteqcc.org/ or via your package manager (apt install fteqcc).
2. From the repo root run:

   fteqcc progs.src  # or use the helper scripts: `build.bat` (Windows) or `./build.sh` (Linux/macOS)

3. Copy the generated progs.dat into your Quake id1 folder (e.g., C:\Games\Quake\id1 or ~/.quake/id1).
4. Launch Quake and start a deathmatch (quake +deathmatch 1 +map dm4).
5. Open the console and run impulse 100 to spawn a Cortex Bot.

Developer guide

• bot.qc implements the AI flow with states such as ROAM, HUNT, COMBAT, RETREAT, FETCH, RIDING, and SOLVE.

• stubs.qc provides stub implementations for standalone testing without a full Quake engine.

• progs.src is the compilation order; keep all listed modules for a successful build.

• Integration notes (scoreboard hooks, impulse bindings, required engine functions) are preserved in README-legacy.md.

• Configuration constants are near the top of bot.qc (close/mid ranges, safe rocket distance, etc.).

• Recent helpers Cortex_CoverDirection and inwater keep Cortex_FindCover and weapon selection from relying on missing math/environment built-ins, so the bot only depends on standard self.waterlevel state and the eight canonical cover directions.

Project layout

• ai.qc, fight.qc, combat.qc, etc. – modular QuakeC source files for different AI responsibilities.
• tools/meqcc14/meqcc.txt – reference for the compiler wrapper.
• progs.src – order enforced by the compiler.
• README-legacy.md, CHANGELOG.md, STATUS.md – historical context, release notes, and progress tracking.

Development

• Run build.bat (Windows) or ./build.sh (Unix) to produce progs.dat locally.
• CI workflow already installs fteqcc, builds the game code, and fails if progs.dat is missing (see .github/workflows/ci.yml).
• Update STATUS.md and CHANGELOG.md whenever features or bugs change.
• On Windows, run the bundled compiler at tools\\fteqcc_win64\\fteqcc64.exe progs.src (the same binary used here) to reproduce progs.dat generation; the current warnings now only cover the longstanding unreferenced locals and not missing math/environment helpers.

Community & collaboration

• Report bugs or suggest enhancements via Issues (templates guide the required details).
• Submit pull requests using the standard template so maintainers can quickly review the intent and testing steps.
• Review CONTRIBUTING.md for branching strategy, coding tips, and testing expectations, and follow the CODE_OF_CONDUCT.md policies when interacting.
• Sensitive vulnerabilities belong in SECURITY.md's reporting instructions instead of public issues.

License

This project is MIT licensed — see LICENSE for details.