A.I. Wars is a turn-based battle simulation where autonomous agents called Cybugs compete on a 2D grid map. Each Cybug is driven by an AI script written in CAICL (Cybug AI Command Language). Cybugs use movement, weapons, sensors, and tactics to destroy opponents and accumulate the highest score.

Up to 10 Cybugs can battle simultaneously. Cybugs with matching IFF codes form teams and will not attack each other. Battles end when only one team remains, or when the tick limit is reached.

1. Open the Battle Setup tab (active by default).
2. Enable one or more Cybug Slots by checking their checkbox.
3. Load an AI script (.ai or .txt) into each active slot by clicking the script button.
4. Drag-and-drop a .map file onto the Map panel, or click the drop zone to browse.
5. Adjust Battle Settings as needed.
6. Click ▶▶ LAUNCH BATTLE.
7. When the battle completes, the Battle Viewer tab opens automatically. Click PLAY to watch.

ⓘ The application must be served over HTTP (not opened as a file://) for the Web Worker engine to function. Use VS Code Live Server, Python SimpleHTTPServer, or any local web server.

ⓘ Deployment, folder structure, and configuration (config.json, cache control, adding maps/cybugs) are covered in README.TXT included with the application files.

Control	Description
Checkbox	Enable or disable this slot for the battle.
Name field	Display name for the Cybug (auto-filled from script).
Team field	Team number used to generate the initial IFF code when IFF Disabled is off.
Script button	Load a .ai / .txt file from disk or server, or open the built-in editor. Green = script loaded. Yellow = debug watch active.
Editor	Full-screen CAICL script editor with syntax coloring. Save or download from within the editor.
Password protection	Scripts can be encrypted. A password prompt appears if the correct key is not supplied for a debug-watch request.

Setting	Default	Description
Stop at Tick	2000	Maximum number of turns before battle is forced to end.
Max Damage	10	Damage points required to destroy a Cybug.
Start Fuel	2500	Fuel each Cybug begins with. Fuel is consumed each turn; a Cybug with 0 fuel is frozen.
Start Ammo	30	Ammo each Cybug begins with. Required for weapons and cloak.
Overheat Limit	30	Shield heat units before the shield auto-shuts down.
IFF Disabled	Off	When checked, all Cybugs receive unique IFF codes and fight solo — no teams.
Shield Overheat Disabled	Off	When checked, shields cannot overheat regardless of use.
Smart Clicks Disabled	Off	When checked, disables the smart-click subsystem (scan commands cost more ticks).

The LAUNCH CONTROL panel contains the launch button, a progress indicator, and a live scoreboard table showing each active Cybug's slot number, name, score, damage, fuel, and ammo. IFF codes are intentionally not displayed to keep team strategies private.

Drag a .map file onto the Map panel or click the drop zone to browse. The map preview renders immediately. The filename and dimensions are shown below the preview.

IFF (Identify Friend or Foe) codes determine team allegiance. Cybugs with the same IFF code are allies — they cannot damage each other with weapons or mines.

• IFF codes are set by the AI script: iff code ALPHA
• If multiple Cybugs use the same code, they form a team and share the same color in the viewer.
• In the Battle Setup, the Team field assigns the initial IFF group (1–5). Scripts can override this at runtime with the iff code command.
• With IFF Disabled checked: all iff code commands in scripts are silently ignored, and each Cybug is permanently assigned a unique IFF — every Cybug fights solo.

The Battle Log shows a verbose play-by-play transcript of the completed battle. It is available after each battle is run and can be downloaded as a text file.

IFF codes are intentionally omitted from the log to keep team strategies private. Each event is time-stamped with a tick number [T=0042] and includes:

• Every move, turn, mine-lay, and mine trigger
• Shell fire with heading, range, damage dealt, and points scored
• Missile and grenade launches, blast results, and shield interactions
• Shield raises/lowers, cloak on/off, repairs, energy discharges
• Fuel-out notifications and destruction events
• Final standings with individual score, team score total, damage, fuel, ammo, and status (ALIVE / FUEL OUT / DESTROYED)

The Debug Watch tab shows a detailed line-by-line execution trace for one selected Cybug slot. Each row shows exactly what the AI interpreter executed and why — invaluable for tracing logic errors and verifying variable assignments.

To enable debug watch for a slot, click the script button for that slot and activate the debug watch toggle (you may be prompted for a password if the script is encrypted). Debug output is hidden if the wrong password is supplied.

Each row uses a fixed-column format matching the original A.I. Wars engine:

DEBUG DATA FOR CYBUG: #01 turtle
CLICK  SC LINE COMMAND
-----  -- ---- ----------------------------------------
1      4   17  math v8 = 23 - 17
1      4   17  assign v8 6
1      6   19  if value 6 > 0 then goto gowest
1      6   19  >>> condition met executing command: goto gowest
1      6   19  goto gowest
3      1   99  long range scan
3      3   99  >>> scan identified: barrier

Column	Description
CLICK	Battle turn number.
SC	Sub-click within the turn (0–9). Scan commands cost +2 sub-clicks.
LINE	Script line number being executed.
COMMAND	The command text. Math commands also emit an assign vN value line showing the computed result. When a conditional is true, a >>> condition met annotation appears followed by the action taken. Scan commands emit a >>> scan identified: result line after the scan completes.

Control	Description
PLAY / PAUSE	Start or pause battle playback. Spacebar also toggles.
RESET	Return to tick 0 and stop playback.
REPLAY	Reset and immediately begin playing from the start.
Speed slider	Playback speed multiplier: 1× (real-time) to 20× (fast-forward).
NAMES toggle	Show or hide Cybug name labels on the battlefield.
SFX toggle	Mute or unmute sound effects.
Progress bar	Shows current position through the battle. Tick counter updates in real time.

Element	Appearance	Description
Cybug	Colored beetle sprite	Body, head, legs, and mandibles face the current heading direction. Color = team. Queens wear a gold crown. Flashes red on overheat/damage. Semi-transparent when cloaked.
Shield	Teal glowing halo	Shown when a Cybug has its shield raised.
Missile	Glowing colored dot	Travels cell-by-cell from launcher to detonation point.
Grenade	Yellow pulsing dot	Travels to fuse distance then explodes.
Mine	Purple X marker	Placed by a Cybug or pre-loaded from the map file. Both types look identical and behave identically — any Cybug stepping on one triggers the same explosion.
Explosion	Orange/white flash	Small for mines/shells; large for missiles, grenades, and destruction events.
Destroyed flag	Green flag marker	Marks the last position of a destroyed Cybug.
Scan flash	Red cell highlight	Visible in the Follow Cam only — shows cells the followed Cybug just scanned.

The Follow Cam panel tracks a single Cybug with a zoomed-in view. Select a target from the dropdown and adjust zoom with the slider. The Follow Cam renders the same beetle sprites, mines, projectiles, and explosions as the main map — the target Cybug is highlighted with a pulsing ring. Scan flashes appear in the Follow Cam only, showing cells illuminated by the most recent scan command.

The right-side scoreboard shows live stats for each active Cybug. Dead Cybugs are grayed out. Fuel and damage bars update every tick. The ♛ QUEEN indicator (gold) appears only for Cybugs that have achieved queen status.

Field	Description
SCR	Current score.
DMG	Damage taken (out of max damage setting).
FUEL	Remaining fuel. Bar empties as fuel drains.
AMMO	Remaining ammo.
HEAT	Shield heat accumulator. Rises while shield is up; resets when shield drops. If it reaches the overheat limit, the shield auto-shuts down.
BURN	Fuel burn rate per tick. Increases with damage and active systems (shield, cloak, weapons).
♛ QUEEN	Shown in gold only when this Cybug has been elevated to queen status.

When the battle ends, an overlay announces the winner and the final top-5 scores. Click anywhere on the overlay or use RESET / REPLAY to continue.

name    My Cybug
author  My Name
iff code ALPHA

The name and author lines are metadata only. iff code sets the team identifier (see IFF & Teams above).

Command	Description
move forward	Move one cell in the current heading direction.
move backward	Move one cell opposite to heading (does not change facing).
turn left	Rotate 90° counter-clockwise.
turn right	Rotate 90° clockwise.

Command	Ammo	Fuel	Description
fire	1	—	Fire a shell up to 5 cells in heading direction. Damage decreases with range. Shielded target: 2/1/0/0/0 dmg; Unshielded: 5/4/3/2/1 dmg. Shields reduce incoming shell damage.
launch missile	10	300	Fire a missile in heading direction. Travels until it hits something. Direct hit: 6 dmg (shielded) / 9 dmg (unshielded); Splash (adjacent cells): 4/7 dmg. Shields reduce missile damage.
launch grenade	5	200	Throw a grenade. Travels to fuse distance then explodes. Direct: 4/7 dmg; Splash: 2/5 dmg (shielded/unshielded). Shields reduce grenade damage.
set grenade fuse N	—	—	Set grenade travel distance to N cells before detonation.
lay mine on / lay mine off	2	—	Toggle mine-laying mode. While on, a mine is placed on each cell the Cybug leaves. Mines deal 5 damage when triggered.
energy discharge	varies	—	Zap all 8 adjacent cells simultaneously. Damages/destroys flags and mines. Also damages the Cybug itself.
self destruct	—	—	Destroy this Cybug and damage all adjacent Cybugs (friend or foe).

Command	Description
raise shield	Activate shield. Incoming damage is reduced but shield heat accumulates. Auto-shuts at overheat limit.
lower shield	Deactivate shield manually.
cloak on	Enable stealth. Cybug becomes harder to detect by scanners. Costs ammo each tick.
cloak off	Disable stealth.
repair	Reduce current damage by the repair amount. Has no effect if not damaged.

All scan commands store their result in the #scan token. Results: friend, enemy, barrier, mine, nothing.

Command	Description
scan perimeter	Check all 8 surrounding cells. Returns the most significant result.
cross scan	Check the 4 cardinal cells (N, E, S, W).
corner scan	Check the 4 diagonal cells (NE, SE, SW, NW).
scan forward	Check the cell directly ahead.
scan left	Check the cell to the left (relative to heading).
scan right	Check the cell to the right (relative to heading).
scan position N	Check one cell at compass direction N (1=N, 2=NE, 3=E, 4=SE, 5=S, 6=SW, 7=W, 8=NW).
scan relative N	Check one cell at direction N relative to heading (1=ahead, 2=right, 3=behind, 4=left, etc.).
long range scan	Scan multiple cells ahead in heading direction. Returns first non-empty result.
gps scan x N y N	Check a specific map coordinate for occupancy.

Command	Description
if scan found X then action	X = friend, enemy, barrier, mine, nothing. Execute action if last scan matched.
if value #var op N then action	Compare a variable or token against a number. op = < > = <= >=
if fuel is op N% then action	Test fuel as a percentage of starting fuel.
if damage is op N% then action	Test damage as a percentage of max damage.
if ammo is op N then action	Test ammo count directly.
if no ammo then action	Execute action if ammo is zero.
if bump barrier then action	Execute action if last move was blocked by a wall or Cybug.
if shield is up then action	Execute action if shield is currently raised.
if shield is down then action	Execute action if shield is lowered.
if facing north then action	Test heading: north, east, south, or west.
if missile ready then action	Execute action if no missile is currently in flight from this Cybug.
if grenade ready then action	Execute action if no grenade is currently in flight from this Cybug.
if random is N then action	True with 1-in-N probability.
if x coordinate is op N then action	Test current X position on the map.
if y coordinate is op N then action	Test current Y position on the map.

Command	Description
assign v1 = #token	Store a token value into variable v1–v38.
math v1 = v2 + v3 * v4	Left-to-right arithmetic (no operator precedence). Operators: + - * /
cmath v1 = (v2 * 3) + 1	Full expression evaluation with standard precedence and parentheses.
generate random v1 N	Store a random integer from 0 to N-1 in v1.

Token	Description
#fuel	Current fuel (0 – start_fuel)
#ammo	Current ammo (0 – start_ammo)
#damage	Current damage taken (0 – max_damage)
#score	Current score
#scan	Last scan result (friend / enemy / barrier / mine / nothing)
#x_pos	Current map X coordinate
#y_pos	Current map Y coordinate
#heading	Current heading (1=N, 2=E, 3=S, 4=W)
#shield	Shield status (0=down, 1=up)
#cloakstatus	Cloak status (0=off, 1=on)
#burnrate	Current heat / burn rate
#overheatset	The configured overheat limit

Command	Description
label myloop	Define a jump target named myloop.
goto myloop	Unconditional jump to a label.
gosub myloop	Jump to label; save return address on the call stack.
return	Return from the most recent gosub.
data link command goto myloop	Send a cross-slot command to a teammate's data link listener.

Map files are plain text (.map). Each character represents one cell on the grid. All rows must be the same width.

Character	Meaning
. (period)	Open ground — passable.
* or W	Wall / barrier — impassable.
9	Pre-placed mine. Looks and behaves identically to Cybug-laid mines — displayed as a purple X marker and explodes on contact, dealing the same damage.
F	Flag / objective cell. Cybugs score points for occupying flags.
I	Slot 1 start position.
J	Slot 2 start position.
K – R	Slots 3–10 start positions (K=3, L=4, M=5, N=6, O=7, P=8, Q=9, R=10).

ⓘ Start positions in the map file must match enabled slots, otherwise the Cybug will default to position (1,1).

Weapon	Shielded Dmg	Unshielded Dmg	Ammo Cost	Fuel Cost
Shell (range 1)	2	5	1	—
Shell (range 2)	1	4	1	—
Shell (range 3)	0	3	1	—
Shell (range 4)	0	2	1	—
Shell (range 5)	0	1	1	—
Missile (direct hit)	6	9	10	300
Missile (splash)	4	7	—	—
Grenade (direct hit)	4	7	5	200
Grenade (splash)	2	5	—	—
Mine (trigger)	5	5	2 (lay)	—

ⓘ Shields reduce incoming damage from all weapon types. Shells at ranges 3–5 deal zero damage to shielded targets. Note that shield heat accumulates while raised — if overheat limit is reached, the shield shuts down automatically.

• Conserve fuel. Movement, weapons, and cloak all drain fuel. A Cybug that runs out of fuel is frozen and helpless — a sitting target.
• Use shields wisely. Shields reduce damage from all weapons. They are especially effective against shells at range — range 3+ shells deal zero damage to a shielded Cybug. However, shield heat builds each tick the shield is up, so don't leave it raised indefinitely or it will overheat and shut off.
• Scan before you move. Bump detection alone isn't enough. Use scan forward before moving into tight corridors.
• Set the grenade fuse. A grenade with the wrong fuse will explode far from the target. Use gps scan to measure distance and set fuse accordingly.
• Use gosub for reusable routines. Break complex behavior into subroutines with labels and gosub/return to keep scripts manageable.
• Use data link for team coordination. Teammates can share commands via data link to coordinate attacks or warn of enemy positions.
• Random behavior beats predictability. Use generate random and if random is N then to make your Cybug harder to predict and outmaneuver.
• Watch the Battle Log. The verbose log shows exactly what happened and why — invaluable for debugging unexpected AI behavior.