Borg¶

The Borg is an “Automatic Angband Player”.

It was first written for about 2.8.0, separate from the game as distributed. It was pulled into the game in around 3.3. It was removed in 4.0 as there was too much conflict with the big changes made then. It was reincorporated in around 4.2.3.

The name comes from “The Borg” in Star Trek which, in turn, comes from cyborg.

The primary use of the Borg is entertainment. It is fun to watch the Borg play the game, and it can be amusing to see how it handles situations. It has been used to test the game and find bugs.

Running The Borg¶

It is not recommended to run the Borg on a live game, as it could cause unexpected behavior or even crashes. It is best to run the Borg on its own save file, or on a copy of your save file.

To run the Borg:

Ensure Angband is compiled with borg support (this is controlled by ALLOW_BORG)
Start or load a game
Press ^z (Ctrl-Z) to access the Borg command interface
Press z to activate the Borg
Watch the Borg play automatically
Press any key to stop the Borg when desired

Borg Command Interface¶

The Borg command interface is only available when Angband is compiled with borg support.

To access the Borg command interface, press ^z (Ctrl-Z) during gameplay. When you first run the command you’ll be presented with a warning message you can continue through. The most common command is z which starts the Borg.

Pressing any key while the Borg is running will stop the Borg.

Main Commands¶

`?`	Display Help
`c`	Toggle cheat death flag
`C`	List count of ‘nasties’
`f`	Toggle flags
`F`	Fear levels of current location
`G`	Display selected grid Features
`h`	Borg_Has function
`I`	Display selected grid Information
`D`	Display selected grid Danger
`l`	Create a snapshot log file
`m`	Map information
`o`	Object Information
`p`	Borg Power
`P`	Level preparation information
`R`	Respawn Borg
`s`	Search mode
`S`	Dump spell info
`t`	Display targeting
`u`	Update the Borg’s variables (as if taking zero steps)
`v`	Version stamp
`w`	My Swap Weapon/Armor
`x`	Step the Borg
`y`	Last 75 steps
`z`	Activate the Borg
`!`	Time
`$`	Reload borg.txt
`@`	Borg LOS
`^`	Flow Pathway
`0`	Borg stats (str/int etc)

Map Information¶

After pressing m from the main borg interface you enter map information display mode. This is map information as the borg understands it. The following selections can be made.

`a`	Avoidances - dangerous areas with level of danger.
`f`	Features with subselection of which feature to show.
`g`	Glyph locations
`m`	Monsters
`o`	Objects

Flag Commands¶

After pressing f from the main borg interface you enter flag toggle mode. You will be able to select any borg configuration and change its runtime value.

Borg_has Commands¶

After pressing h from the main borg interface you enter “has” display mode. These are things the borg has. The list is put in the games messages.

`a`	Any
`i`	Inventory
`w`	Worn items
`r`	Artifacts
`s`	Skills

Search Mode¶

After pressing s from the main borg interface you enter a search string. If the borg sees that string in the messages it will stop. Default is “plain gold ring” for The One Ring.

Customizing The Borg¶

The Borg’s behavior is primarily configured through the borg.txt file. This allows for extensive customization of the Borg’s decision-making without needing to recompile the game.

A sample borg.txt file is provided in the src/borg directory of the source code. To use it, copy this file to the user preferences directory for your operating system, and then customize it.

Windows: Copy src/borg/borg.txt to lib/user/borg.txt
macOS/Linux: Copy src/borg/borg.txt to ~/.angband/Angband/borg.txt

Once copied, you can edit borg.txt to change the Borg’s behavior. To apply changes while the game is running, use the $ command from the Borg command interface (^z).

How you customize the Borg depends on whether you are using a pre-compiled build or compiling from source.

Configuration Options¶

The borg.txt file offers a wide range of options to customize the Borg’s behavior. Below is a summary of the key settings. For a complete list and detailed explanations, refer to the comments within the borg.txt file itself.

Adjusting Borg Speed¶

When you first run the Borg it may move very slowly. This is often due to the game’s base delay factor, a general setting that affects all animations. To speed up the Borg you can decrease this value:

Press = to open the main options menu
Press d to change the delay factor
Decrease the value

Conversely, if the Borg is moving too quickly to follow, you can increase this value. You can also add a Borg-specific delay by setting borg_delay_factor in borg.txt.

Worships¶

These settings (e.g., borg_worships_damage, borg_worships_gold) influence the Borg’s priorities and decision-making by assigning value to different actions and items. For example, they can make the Borg favor powerful weapons, seek out treasure, or prioritize speed.

Play Style¶

borg_plays_risky: Makes the Borg dive deeper faster and be more aggressive in combat
borg_kills_uniques: Forces the Borg to defeat uniques before proceeding deeper into the dungeon

Item Management¶

borg_uses_swaps: Allows the Borg to carry and use swap items for situational resistances and abilities
borg_worships_gold: Causes the Borg to return to town frequently to sell items for gold, especially at lower levels

Respawn and Continuous Play¶

borg_cheat_death: If enabled, the Borg will not die and will continue playing, enabling continuous play. This can be set in borg.txt or toggled via the Borg command interface (^z, then c, then d)
borg_respawn_race and borg_respawn_class: Specify the race and class for the next character when the Borg respawns
borg_respawn_winners: If enabled, the Borg will create a new character after defeating Morgoth

Dynamic Formulas¶

The Borg can use either its internal hard-coded logic for decision-making or a more flexible system of dynamic formulas defined in borg.txt. To enable the formula-based system, set the following in borg.txt:

borg_uses_dynamic_calcs = TRUE

The dynamic calculations are more customizable but may be slower and are not always as up-to-date as the internal code logic.

Using Official Builds¶

In most official builds, Borg support is already included and enabled. You just need to copy and configure the borg.txt file in the correct location as described above.

Compiling Yourself¶

When compiling from source, the Borg is enabled by default on most platforms. For starter instructions on how to compile, see the Compiling Instructions guide.

If you find the Borg is disabled in your build configuration, you can typically enable it by:

Uncommenting an allow_borg line in a configuration file (like config.h)
Passing a -DALLOW_BORG flag to the compiler

When compiling, you can also enable the SCORE_BORGS flag to allow Borg characters to appear in the high score list. This is disabled by default.

Refer to the compilation instructions for your specific platform for details. After compiling with Borg support, place your borg.txt file in the correct location as described above.

Borg Logging¶

The Borg suppresses most messages by default. To see what the Borg is doing, you’ll want to use multi-window support to display additional information windows.

Window Configuration¶

For optimal Borg monitoring, open additional terminal windows to display:

Equipment: See what the Borg is wearing and wielding
Messages: View game messages and Borg status updates
Monster Recall: See information about monsters the Borg encounters
Inventory: Monitor what items the Borg is carrying

Set these up through the window menu before activating the Borg. Borg-specific messages will appear in the Messages window when verbose mode is enabled.

Verbose Mode¶

Enable verbose mode to get detailed output about the Borg’s decision-making process, including calculations, target selection, danger assessment, and action decisions.

Via Flag Command¶

Press ^z to access the Borg command interface
Press f to enter flag toggle mode
Select borg_verbose to toggle verbose mode on/off

Via Configuration¶

Set borg_verbose = TRUE in the borg.txt configuration file, then reload with ^z $.

Log Snapshot¶

Create a detailed snapshot of the current game state for debugging:

Press ^z to access the Borg command interface
Press l to create a snapshot log file

This generates a comprehensive .map file (e.g., player_name.map) in your Angband archive directory containing:

ASCII dungeon map: Current level layout showing terrain, monsters (&), items, and player (@) position
Recent game messages: Last actions, movements, and events
Complete character state: Equipment, inventory, quiver, and home contents
Borg configuration: Current swap items and borg settings
Detailed statistics: All internal borg trait values, resistances, and assessments

The snapshot provides a complete picture of both the game state and the Borg’s internal knowledge at that moment, useful for understanding its behavior or debugging issues.

Borg Screensaver¶

The Borg can be configured to run as a Windows screensaver that automatically plays the game in continuous play mode, automatically restarting with new characters when the current character dies.

WARNING: The Angband display is not always dynamic. While modern LCD monitors are not susceptible to burn-in, OLED displays may still experience image retention with prolonged static content. Configure energy saving settings to turn off your monitor after inactivity. The screensaver keeps the processor and hard disk busy, preventing power-saving features that depend on inactivity.

Installation¶

Copy angband.scr and the included angband.ini into your Windows directory
Ensure you have the Windows version of Angband installed with all supporting files in the lib directory
Edit angband.ini with a text editor:
- Set AngbandPath to point to your Angband installation directory (must end with a backslash \)
- Set SaverFile to the character name you want to use for the screensaver (a random character will be automatically created if the character doesn’t exist)
Example configuration:
```
[Angband]
AngbandPath="c:\games\angband-4.2.5\"
SaverFile="Saver"
```
Test the screensaver in Windows Display Properties

It’s recommended to create a normal character first using regular Angband, set up your terminal windows as desired, save that file, and use that filename as the SaverFile for your screensaver.

Technical Details¶

The screensaver is a renamed Windows Angband executable with modified main-win.c
Normal Borgs get highscore entries, but screensaver Borgs (continuous play mode) do not
Uses low priority processing to avoid slowing down other processes
- Can be toggled via “Options/Low priority” menu when using as normal executable for background Borg play
Uses the normal Angband installation’s angband.ini for screen layout, graphics, and sound settings
Can be used as a normal Angband executable by renaming to angband.exe

Known Limitations¶

No preview in Windows Display Properties
Password protection not implemented
Configuration requires manual ini file editing
“Show scores” while Borg is running may cause crashes
Cannot run the same savefile simultaneously (e.g., normal game and screensaver)
Info window sizes may increase when exiting pseudo-screensaver mode from options menu

The Angband Manual