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

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


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

MagicTree 3.4 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.4 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 remains a classical handcrafted-evaluation engine. It does not use
NNUE and does not require an external network file. The release executable uses
a PEXT/BMI2 sliding-attack backend and targets 64-bit x86 processors supporting
AVX2 and BMI2. It may fail to start on older processors without these features.

The 2830 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.4.exe
    Optimized static Windows x64 UCI executable.

Src\
    Comment-free C++17 source code and the reproducible PEXT 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.4_readme_OPEN_SOURCE_MIT.txt
    This release document and a copy of the MIT License.

LICENSE_MagicTree_3.4_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.4.exe".
3. Choose UCI as the engine protocol if the GUI asks.
4. Confirm that the engine reports:

   id name MagicTree 3.4
   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.4.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 -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 debug paths, fixes the PE build epoch, compiles the executable,
checks its identity, installs "MagicTree 3.4.exe", and removes the temporary
staging files.

Expected executable SHA-256:

   BECCA266A7FD755B3D6366584082913B5FE28A24F67584F857A2ECD6D4D966A1

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 draw
    scoring. Positive values make the engine less willing to accept a draw.

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.4 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 a grouped middle-game/endgame evaluation trace.

    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.4 compared with MagicTree 3.3
-------------------------------------------------------

A. Identity and UCI analysis features

- The UCI identity is updated from MagicTree 3.3 to MagicTree 3.4.
- MultiPV is added with a range of 1 to 8 lines. Secondary root lines are
  searched after excluding stronger moves already found. MultiPV 1 retains the
  normal aspiration-windowed single-PV search and played-move behavior.
- Contempt is added with a range of -100 to +100 centipawns. Draw scores are
  made root-relative throughout main search and quiescence search, including
  repetition, insufficient-material, and stalemate paths.
- Principal variations can be extended for display from legal TT moves after
  the searched triangular PV ends. The extension rejects absent or illegal
  moves, repetition cycles, and excessive length and does not alter the score
  or selected move.

B. Move-generation architecture

- Move generation now builds and reuses a GenerationContext containing side,
  king square, occupancy, check state, double-check state, target mask, pinned
  pieces, and per-square pin rays.
- The generator can produce tactical moves and quiet moves separately instead
  of constructing one complete candidate list at every picker node.
- Check evasion masks are assembled directly from the checker square and the
  interposition squares for sliding checks.
- A dedicated pseudo-legal validator was added for TT, killer, counter, and
  specialized-picker moves. It validates piece ownership, move flags, captures,
  en passant, pawn pushes, promotions, sliding geometry, castling rights and
  transit safety, pins, checks, and king safety.
- Castling is generated only for quiet/all generation, while captures and
  promotions are generated only for tactical/all generation.
- Move-generation profiling hooks were added for optional profiling builds.

C. Move-picking and ordering

- MovePicker was reorganized into explicit Root, Main, Evasion, QSearch,
  ProbCut, and Recapture modes.
- Main-search ordering is now TT/forced move, good captures, strong early
  refutations, remaining quiets, and bad captures.
- Killer 1, counter move, and killer 2 can be promoted into an early refutation
  stage when pseudo-legal, non-tactical, sufficiently well scored, and SEE-safe.
- Captures are generated and initially ordered without eagerly running SEE on
  every capture. SEE is evaluated lazily as captures reach the front of the
  ordered list; losing captures are deferred for the bad-capture stage.
- Checking captures retain a depth-sensitive allowance for playable tactical
  sacrifices.
- Immediate recaptures receive a dedicated ordering bonus.
- Stable insertion sorting replaces repeated best-element scans for prepared
  capture and quiet lists.
- Specialized ProbCut and recapture pickers restrict generation to the moves
  relevant to those searches and apply their own SEE thresholds.
- The exact direct/discovered check detector is shared with search, avoiding a
  make/unmake cycle solely to determine whether a move gives check.

D. Search and quiescence

- A conservative capture-only ProbCut is added at eligible non-PV nodes from
  depth 6. It uses a raised beta threshold, a static-evaluation guard, SEE-aware
  tactical ordering, a six-move cap, a quiescence verification, and a reduced
  main-search verification before accepting a cutoff.
- Deep quiescence search switches to recaptures on the previous destination
  square from quiescence ply 6, with a controlled negative SEE allowance. This
  limits unproductive tactical explosion while retaining recapture sequences.
- Check-evasion quiescence uses the specialized evasion picker instead of first
  allocating a complete legal-move vector.
- SEE capture pruning is now applied only to actual captures, keeping quiet
  promotions out of a capture-only pruning path.
- The transposition-table bucket for a child position is prefetched after the
  move is made and before the recursive search.
- Per-node diagnostic counters are compiled out of normal release builds. They
  can be restored with MAGICTREE_DIAG; this removes telemetry writes from the
  performance-critical search path without changing decisions.
- Optional profiling was expanded to measure make/unmake, move generation, and
  TT work in addition to evaluation, SEE, scoring, and picking.

E. Static Exchange Evaluation

- see_ge now has safe threshold short-circuits before running the full exchange
  sequence. It rejects moves whose immediate material gain cannot reach the
  threshold and accepts moves whose worst immediate recapture cannot fall below
  it.
- The recapture lower bound conservatively accounts for a pawn promoting on the
  destination square.
- Castling and MOVE_NONE receive a direct zero-gain threshold result.

F. Transposition table

- TT entries are reduced to 16 bytes and four entries are grouped into one
  cache-line-aligned 64-byte bucket.
- Full 64-bit stored keys are replaced by mixed 32-bit verification tags.
- Depth is packed into a signed byte, while the six-bit generation and two-bit
  bound are packed together.
- Requested hash memory is used directly through any bucket count rather than
  rounding down to a power of two. Power-of-two tables keep the fast masked
  index; other sizes use multiply-high range reduction.
- Probe, store, replacement, generation aging, hashfull sampling, clearing, and
  prefetching were updated for the packed bucket layout.
- Replacement continues to favor deeper and exact entries while aging stale
  entries through the packed six-bit generation counter.

G. Incremental evaluation and tuning

- Position now maintains incremental non-pawn middle-game score, endgame score,
  and phase. The values are initialized from FEN/board reconstruction, updated
  during piece placement, removal, moves, captures, promotions, and castling,
  and restored exactly by undo and null-move undo.
- Full and lazy evaluation reuse the incremental non-pawn totals and the pawn
  hash instead of rescanning every non-pawn piece for material, PST, and phase.
- New EvalBase accessors centralize the non-pawn middle-game, endgame, and phase
  contribution used by Position.
- Knight, bishop, rook, queen, and king middle-game and endgame piece-square
  tables were retuned.
- Knight, bishop, rook, and queen middle-game and endgame mobility tables were
  retuned.
- Pawn middle-game and endgame piece-square tables in the pawn hash were
  retuned.
- Other handcrafted evaluation terms and the overall classical evaluation
  framework remain inherited from 3.3.

H. Files changed relative to 3.3

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

The implementations in attack.h, fen.cpp/fen.h, move.cpp/move.h, perft.cpp/
perft.h, pext.cpp/pext.h, timeman.cpp/timeman.h, types.h, utils.h,
zobrist.cpp/zobrist.h are unchanged from the 3.3 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 endgame tablebase probing is included.
- 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, 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.
