====
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 also 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:

1. Ensure Angband is compiled with borg support (this is controlled by
   ``ALLOW_BORG``).  This is done by default in most distributions.
2. Start or load a game
3. Press ``^z`` (Ctrl-Z) to access the Borg command interface
4. Press ``z`` to activate the Borg
5. Watch the Borg play automatically
6. 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. If you do not have a ``borg.txt`` file a 
stripped down ``borg.txt`` will be generated when the borg is first started.

For source distributions 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``
- Linux\Unix: Copy ``src/borg/borg.txt`` to ``~/.angband/Angband/borg.txt``
- macOS with the Cocoa front end:: Copy ``src/borg/borg.txt`` to 
  ``Documents/Angband`` within your home directory 

If you are using a binary distribution of Angband, the default borg.txt file 
needs to copied from the spot where it was put in the distribution for that
platform.

- Windows: the ``borg.txt`` file is already in the user preferences directory.
- macOS with the Cocoa front end: ``borg.txt`` is included in the top level 
  directory of the dmg file from which you installed the game.
- Linux/Unix: the ``borg.txt`` may not have been included in the distribution
  or it might be in ``/usr/share/doc/angband/borg.txt``.  If it is not found it
  can be copied from the source distribution in ``src/borg/borg.txt`` or
  downloaded from github.

To download the ``borg.txt`` from github (https://github.com/angband/angband)
select the ``<> Code`` tab.  Then select the ``src`` directory, the ``borg``
subdirectory and download the ``borg.txt`` from there.  If you need an older 
version use the ``History`` link for that file to find the correct version.

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:

1. Press ``=`` to open the main options menu
2. Press ``d`` to change the ``delay factor``
3. 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``:

.. code-block:: ini

  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 :doc:`compiling` 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 :ref:`window menu <showing-extra-info-in-subwindows>`
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
****************

1. Press ``^z`` to access the Borg command interface
2. Press ``f`` to enter flag toggle mode
3. 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:

1. Press ``^z`` to access the Borg command interface
2. 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
------------

1. Copy ``angband.scr`` and the included ``angband.ini`` into your Windows
   directory

2. Ensure you have the Windows version of Angband installed with all supporting
   files in the ``lib`` directory

3. 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"

4. 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
