MagicTree 3.5 - README and Open-Source License
===============================================

Engine name:   MagicTree 3.5
Executable:    MagicTree 3.5.exe
Author:        Vikrant Malvankar
Country:       India
Protocol:      UCI - Universal Chess Interface
Release label: 2900 Elo
Release type:  Open-source source-code and binary release under the MIT License
Document date: 20 September 2026


1. Overview
-----------

MagicTree 3.5 is a 64-bit Windows UCI chess engine. Load the executable into a
UCI-compatible chess GUI such as Arena, Cute Chess, BanksiaGUI, Shredder,
Fritz/ChessBase, or another interface that supports UCI engines.

MagicTree 3.5 is released as open-source software under the MIT License. The
source code may be used, copied, modified, merged, published, distributed,
sublicensed, and/or sold subject to the MIT License printed in this README and
supplied in the accompanying LICENSE file.

MagicTree is an engine only. It does not include a graphical chess board,
opening-book manager, tournament manager, or analysis GUI.

This release uses a classical handcrafted evaluation. It does not use NNUE and
does not require an external network file. The release executable uses a
PEXT/BMI2 sliding-attack backend, AVX2 code generation, and link-time
optimization. It targets 64-bit x86 processors supporting AVX2 and BMI2 and
may fail to start on older processors without these features.

The 2900 Elo label identifies this release line. Ratings vary materially with
hardware, time control, opening suite, concurrency, adjudication, and opponent
pool, so it should not be read as a universal rating on every list.


2. Package layout
-----------------

MagicTree 3.5.exe
    Optimized static Windows x64 UCI executable.

Src\
    Comment-free C++17 source code and the reproducible PEXT/LTO build script.

Src\build-pext.ps1
    Builds the release with the exact compiler options used for the supplied
    executable and verifies its SHA-256 identity before replacing the output.

MagicTree_3.5_readme_OPEN_SOURCE_MIT.txt
    This release document and a copy of the MIT License.

LICENSE_MagicTree_3.5_MIT.txt
    Standalone MIT License.


3. Quick start
--------------

A. Using a chess GUI

1. Open the GUI's engine installation dialog.
2. Select "MagicTree 3.5.exe".
3. Choose UCI as the engine protocol if the GUI asks.
4. Confirm that the engine reports:

   id name MagicTree 3.5
   id author Vikrant Malvankar
   id country India

5. Keep the default options for normal play unless a different setting is
   specifically required for analysis or testing.

B. Command-line smoke test

Start "MagicTree 3.5.exe" and send:

   uci
   isready
   ucinewgame
   position startpos
   go depth 10
   quit

Expected responses include "uciok", "readyok", iterative UCI information, and
a final "bestmove ..." line.


4. Source and reproducible build
--------------------------------

The release was built with MSYS2 MinGW-w64 GCC 15.2.0. Run the supplied script
from PowerShell:

   .\Src\build-pext.ps1

The build uses:

   -DNDEBUG -m64 -std=c++17 -O3 -flto -march=haswell -mavx2 -mbmi2
   -static -static-libgcc -static-libstdc++ -Wl,-Bstatic -lwinpthread

The script stages the source files temporarily at the release root to preserve
the original build paths, fixes the PE build epoch, compiles the executable,
checks its identity, installs "MagicTree 3.5.exe", and removes the temporary
staging files.

Expected executable SHA-256:

   38C3E05ED0E07C6DCBF2FAD2985DDAA8A65E10B941A2111C1A2B1615C4B44CAB

The supplied binary and a fresh build from the supplied comment-free sources
are byte-for-byte identical when the documented GCC 15.2.0 toolchain is used.

The file perft.cpp can also provide a standalone perft/regression executable
when PERFT_BUILD is defined and uci.cpp is omitted. For the normal UCI engine,
include perft.cpp without defining PERFT_BUILD.


5. UCI options
--------------

Hash
    Default 64 MB; range 1 to 4096 MB. Controls transposition-table memory.

MultiPV
    Default 1; range 1 to 8. Reports the requested number of principal
    variations for analysis. A value of 1 retains the normal single-PV path.

Contempt
    Default 0; range -100 to 100 centipawns. Changes the root-relative value of
    draws, including repetitions and stalemates. Zero keeps objective scoring.

Move Overhead
    Default 30 ms; range 0 to 5000 ms. Clock and communication safety margin.

Minimum Thinking Time
    Default 20 ms; range 0 to 5000 ms. Minimum managed search allocation.

Slow Mover
    Default 100; range 10 to 500. Time-management multiplier.

Advanced search and tuning options:

    SeeCaptureMargin       default 32    range 0 to 200
    SeeCaptureDepth        default 6     range 0 to 12
    SeeQuietMargin         default 40    range 0 to 400
    SeeQuietDepth          default 10    range 0 to 12
    SeeEndgameGuard        default 0     range 0 to 32
    SeeCaptHistDiv         default 512   range 0 to 4096
    SeeQuietHistDiv        default 512   range 0 to 4096
    CorrPawnWeight         default 2     range 0 to 8
    CorrNonPawnWeight      default 1     range 0 to 8
    CorrContWeight         default 1     range 0 to 8
    CorrWeightScale        default 2     range 1 to 8

These advanced options expose SEE-pruning and correction-history parameters
for controlled testing. The defaults are the release settings.


6. Supported commands
---------------------

MagicTree 3.5 supports the main UCI workflow:

    uci
    isready
    ucinewgame
    setoption name <option> value <value>
    position startpos [moves ...]
    position fen <FEN> [moves ...]
    go depth <n>
    go movetime <ms>
    go wtime <ms> btime <ms> [winc <ms>] [binc <ms>] [movestogo <n>]
    go nodes <n>
    go infinite
    stop
    quit

Diagnostic commands:

    d
        Prints the current FEN and board.

    eval
        Prints the full static evaluation from the side-to-move perspective.

    evaltrace
        Prints grouped middle-game/endgame evaluation contributions.

    perft <depth>
        Runs a legal move-generation perft count. From the initial position,
        perft 5 must return 4,865,609 nodes.


7. Changes in MagicTree 3.5 compared with MagicTree 3.4
-------------------------------------------------------

A. Identity and release build

- The UCI identity is updated from MagicTree 3.4 to MagicTree 3.5.
- The optimized static PEXT release adds whole-program link-time optimization
  while retaining the 64-bit Haswell/AVX2/BMI2 target used by the release line.
- The public UCI option set remains compatible with 3.4.

B. Evaluation retuning

- The handcrafted evaluation was broadly retuned across bishop-pair bonuses,
  knight and bishop closed-position behavior, outposts, bad bishops, long
  diagonals, king protection, rook files and seventh-rank activity, trapped
  rooks, piece synergies, material imbalance, threats, safe checks, king-ring
  pressure, passed pawns, king activity, mobility, tempo, and space.
- Knight, bishop, rook, and queen middle-game/endgame mobility curves were
  refined. Piece-square tables received further square-level adjustments.
- Pawn evaluation was retuned for doubled, isolated, backward, defended,
  phalanx, candidate, and passed-pawn structures. Pawn piece-square tables,
  king shelter, open-file exposure, adjacent-file exposure, and pawn storms
  were also refined.
- Threat evaluation now gives separate tuned treatment to hanging pieces and
  queens, restricted pieces, safe pawn attacks, pawn-push threats, attacks on
  the queen, and minor/major-piece victim classes.
- The tapered evaluator now uses packed middle-game/endgame scores internally,
  reducing duplicated arithmetic while preserving independent phase values.
- Evaluation tracing was expanded so material, pieces, passers, threats, king
  safety, king activity, space, initiative, scaling, and final evaluation can
  be inspected as separate stages.

C. Exact and specialized endgame knowledge

- A compact KPK bitbase is generated at startup. King-and-pawn versus king is
  classified exactly as win or draw after file/color normalization, and won
  positions receive advancement and king-support guidance.
- A material-keyed endgame registry selects score overrides and scale factors
  for positions of up to seven men.
- Specialized scaling was added for KRPKR, KRPPKRP, KQKP, KRKP, KBPKB, and
  KNPK families, including several defensive drawing formations.
- Bare minor versus king, two knights versus king, and several pawnless equal-
  material endings are recognized as draws. Rook-versus-minor endings receive
  conservative scaling.
- Wrong-colored bishop and rook-pawn fortresses, opposite-colored bishop
  endings, low-pawn endings, and drawish rook endings receive dedicated scale
  treatment.
- Known mating material receives directional guidance: heavy pieces drive the
  defending king away from the center, while bishop-and-knight mate guidance
  drives it toward a bishop-colored corner.
- Endgame initiative now accounts for king outflanking, pawns on both wings,
  passers, queen presence, and nearly unwinnable low-complexity structures.

D. Material and pawn caches

- A 2,048-entry material table caches queen/minor synergies and compensation
  adjustments for minor-piece and rook imbalances by material signature.
- Pawn-hash entries now retain masks for open backward pawns, open candidate
  passers, and advanced connected passers. These masks support coefficient
  tracing without rescanning the board.
- Pawn-structure tests use pawn occupancy bitboards in their hot paths.
- The next pawn-hash bucket is prefetched immediately after a move changes the
  pawn key.

E. Search and position speed work

- Check state is computed when a move is made and passed into child negamax
  and quiescence calls. This avoids recomputing the same attack query on entry
  to every child node. An optional verification build can assert the cached
  state against a fresh calculation.
- Check-extension logic now counts legal evasions only up to the threshold it
  needs, using a fixed move array and targeted legality checks instead of
  allocating and filling a complete legal-move vector.
- Repetition history changed from a dynamically allocated vector to a bounded
  2,048-entry array with explicit length. Long histories retain their newest
  half when the bound is reached.
- Position undo records were compacted to at most 32 bytes with width-matched
  fields for squares, piece indexes, clocks, castling rights, phase, and
  incremental evaluation state.
- Profiling builds now reset all evaluation, SEE, move scoring, move picking,
  make/unmake, move generation, and transposition-table counters per search.

F. Evaluation tuning support

- MAGICTREE_TUNE builds expose selected king-safety, threat, and tempo values
  as UCI spin options without changing the normal release interface.
- Tuning builds can enumerate every supported scalar/table coefficient, set or
  read a coefficient by flat index, and dump a position's sparse middle-game
  and endgame coefficient response.
- Pawn and material caches can be bypassed during coefficient probing so a
  changed parameter is measured immediately and reproducibly.
- The normal release is compiled without MAGICTREE_TUNE; tuning commands and
  mutable parameter storage are therefore absent from the playing binary.

G. Files changed relative to 3.4

Functional changes are present in eval.cpp/eval.h, movegen.cpp/movegen.h,
pawnhash.cpp/pawnhash.h, position.cpp/position.h, search.cpp, and uci.cpp.

The implementations in attack.cpp/attack.h, fen.cpp/fen.h, move.cpp/move.h,
movepicker.cpp/movepicker.h, perft.cpp/perft.h, pext.cpp/pext.h, prof.h,
search.h, timeman.cpp/timeman.h, tt.cpp/tt.h, types.h, utils.h, and
zobrist.cpp/zobrist.h are functionally unchanged from the 3.4 source package.


8. Known limitations and release notes
--------------------------------------

- This build is intended for 64-bit Windows.
- AVX2 and BMI2/PEXT-capable hardware is required.
- MagicTree is a UCI engine and does not include a GUI.
- No opening book is included.
- No external Syzygy or other tablebase probing is included. The internal KPK
  bitbase covers only king-and-pawn versus king.
- No NNUE network is included; this is a classical evaluation release.
- Search is single-threaded and no Threads UCI option is exposed.
- MultiPV is intended for analysis and costs additional search work for every
  secondary line.
- The source files intentionally contain no human or AI explanatory comments.


9. Technical acknowledgements
------------------------------

MagicTree uses established computer-chess concepts documented publicly by the
computer-chess community. Relevant references include:

- Rudolf Huber and Stefan Meyer-Kahlen for the Universal Chess Interface.
  https://www.shredderchess.com/chess-features/uci-universal-chess-interface.html
- Chessprogramming Wiki for documentation of bitboards, move generation,
  alpha-beta/PVS, iterative deepening, aspiration windows, quiescence search,
  null-move pruning, ProbCut, LMR, futility pruning, singular extensions, move
  ordering, history heuristics, transposition tables, SEE, Zobrist hashing,
  tapered evaluation, pawn hashing, bitbases, endgame scaling, and time
  management.
  https://www.chessprogramming.org/
- Gerd Isenberg and other TalkChess contributors for public PEXT-bitboard
  discussion and compact sliding-attack-table techniques.
  https://talkchess.com/viewtopic.php?t=48220
- Intel's x86 instruction documentation for PEXT/BMI2 behavior.
  https://www.felixcloutier.com/x86/pext

These acknowledgements credit ideas, algorithms, protocol specifications, and
public technical references. They do not change the licensing of MagicTree's
source code under the MIT License.


10. MIT License
---------------

Copyright (c) 2026 Vikrant Malvankar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.