MagicTree 3.1 - README and Binary License
===========================================

Engine name: MagicTree 3.1
Executable:  MagicTree 3.1.exe
Author:      Vikrant Malvankar
Country:     India
Protocol:    UCI - Universal Chess Interface
Release type: Free binary-only release; source code is not included.
Document date: 21 May 2026


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

MagicTree 3.1 is a 64-bit Windows UCI chess engine. It is intended to be loaded
into a UCI-compatible chess GUI such as Arena, Cute Chess, BanksiaGUI, Shredder,
Fritz/ChessBase, or any other interface that can run a UCI engine.

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

The 3.1 build uses a PEXT/BMI2 sliding-attack backend. Use this executable on a
64-bit Windows system with a CPU that supports the x86-64 BMI2 instruction set.
If the CPU does not support BMI2/PEXT, this build may fail to start or may crash.
A non-BMI2 build, if needed, should be distributed separately.


2. Quick start
--------------

A. Using a chess GUI

1. Open your chess GUI.
2. Choose the GUI's option to install/add a new UCI engine.
3. Select "MagicTree 3.1.exe".
4. Confirm that the GUI detects the engine as:

   id name MagicTree 3.1
   id author Vikrant Malvankar
   id country India

5. Keep the default UCI options unless you are testing or tuning the engine.
6. Start a game, tournament, or analysis session from the GUI.

B. Command-line smoke test

From Windows Command Prompt or PowerShell:

   "MagicTree 3.1.exe"
   uci
   isready
   ucinewgame
   position startpos
   go depth 10
   quit

Expected responses include "uciok", "readyok", UCI info lines, and a final
"bestmove ..." line.


3. UCI options
--------------

Standard/user-facing options:

- Hash
  Default: 64 MB. Range: 1 to 4096 MB.
  Transposition-table memory used by the engine.

- Move Overhead
  Default: 30 ms. Range: 0 to 5000 ms.
  Safety buffer subtracted from available clock time.

- Minimum Thinking Time
  Default: 20 ms. Range: 0 to 5000 ms.
  Minimum time budget used for time-managed searches.

- Slow Mover
  Default: 100. Range: 10 to 500.
  Time-management multiplier. Higher values generally make the engine spend
  more time per move.

MagicTree 3.1 does not expose Threads, MultiPV, Syzygy, NNUE, or tablebase UCI
options in this release package.


4. Supported commands
---------------------

MagicTree 3.1 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

Additional diagnostic commands:

- d
  Prints the current FEN and an ASCII board.

- eval
  Prints the full static evaluation from the side-to-move point of view.

- evaltrace
  Prints a grouped evaluation trace for development, symmetry checking, and
  evaluation-tuning diagnostics.

- perft <depth>
  Runs a move-generator perft count from the current position.


5. What is new in MagicTree 3.1 vs MagicTree 3.0
-------------------------------------------------

The previous archive supplied for comparison is named "MagicTree 3.0.zip". The
following changes were identified by comparing the supplied MagicTree 3.1 source
archive with the supplied MagicTree 3.0 source archive.

A. Identity and UCI layer

- Engine identity updated from MagicTree 3.0 to MagicTree 3.1 in the released
  executable.
- Added an "eval" diagnostic command that reports the full static evaluation in
  centipawns from the side-to-move point of view.
- Added an "evaltrace" diagnostic command that prints a grouped middle-game /
  end-game evaluation trace with per-group deltas. This is intended for symmetry
  auditing and evaluation-tuning insight.

B. Position legality and hashing correctness

- En-passant target squares are now retained only when a legal en-passant capture
  is actually available.
- FEN loading now clears an en-passant square that cannot legally be captured by
  the side to move.
- Double pawn pushes now set the en-passant square only when the opposing side
  has at least one legal en-passant capture after accounting for king safety.
- This avoids different Zobrist keys for positions that are strategically and
  legally identical because of a phantom en-passant square.

C. Pawn-structure evaluation fixes

- Backward-pawn detection was corrected in both the full evaluator and pawn hash
  logic.
- A pawn with an occupied push square is no longer treated as a backward pawn
  merely because the square in front is attacked.
- The corrected logic requires the square in front of the pawn to be empty and
  attacked by an enemy pawn before the backward-pawn penalty can apply.

D. Static-evaluation exactness and correction history

- Lazy evaluation now returns an EvalResult containing both the score and an
  exact/inexact flag.
- Inexact lazy-eval cutoffs are no longer stored as reusable exact static evals
  in the transposition table.
- Pawn correction history is updated only when the raw static evaluation was an
  exact evaluation, avoiding pollution from lazy-eval shortcut scores.
- Root search, main search, and quiescence search now use the same helper logic
  for probing a TT static eval or obtaining an exact static eval when needed.

E. Quiescence-search robustness

- Quiescence search now distinguishes total search ply from quiescence ply. This
  keeps qsearch depth limits focused on the quiescence part of the search rather
  than on total root-to-leaf ply.
- Qsearch allows in-check positions to continue searching legal evasions even at
  the qsearch depth limit, while quiet non-check positions still stop at the
  configured qsearch cap.
- Checkmate detection in qsearch now tracks whether a legal evasion was actually
  searched, avoiding false mate results in edge cases where generated evasions
  are rejected by legality filtering or all searched evasions fail low.
- Qsearch capture pruning can reuse the MovePicker's cached SEE result instead
  of recomputing SEE for the same capture.

F. Move ordering and speed optimizations

- MovePicker now caches the Static Exchange Evaluation gain for captures.
- The cached SEE value is reused for good/bad capture splitting, checking-sac
  classification, and qsearch capture pruning.
- MovePicker scoring and pick-next routines include optional profiling hooks.
- Large per-node move arrays are no longer value-initialized, because reads are
  bounded by explicit move counts. This reduces avoidable per-node memory work.

G. Dynamic time management

- The soft time limit is now dynamically adjusted during iterative deepening.
- When the best move remains stable across iterations, MagicTree can spend less
  than the original soft budget and save time for later positions.
- When the best move changes at meaningful depth, or the root score drops, the
  soft budget can be extended toward the hard limit.
- Fixed-movetime searches preserve the requested movetime behavior because soft
  and hard limits are equal in that mode.

H. Diagnostic and profiling support

- Added prof.h and optional MAGICTREE_PROFILE instrumentation for eval, SEE,
  move scoring, and move picking. This is a build-time diagnostic feature and is
  inactive in normal builds unless MAGICTREE_PROFILE is defined.
- Added evaluation trace snapshots at key evaluation stages, including pawn hash,
  pieces, bishop pair, queen synergy, material imbalance, passers, threats, king
  safety, king activity, space, initiative, endgame scaling, and final score.

I. Build/output note

- The supplied 3.1 executable is a 64-bit Windows PE console executable.
- The supplied 3.1 source uses PEXT/PDEP intrinsics for sliding attack table
  generation and lookup.
- The source archive contains a fallback internal source identifier of
  "MagicTree 3.1.1" in uci.cpp, but the bundled executable string identifies as
  "MagicTree 3.1". If a future rebuild is made, confirm the displayed UCI name
  before distribution.


6. Known limitations and release notes
--------------------------------------

- This is a binary-only public release. The source code is not included.
- This build is intended for 64-bit Windows.
- This build requires BMI2/PEXT-capable hardware.
- MagicTree 3.1 is a UCI engine, not a standalone chess GUI.
- No opening book is included.
- No endgame tablebase support is included in this release package.
- No NNUE/network file is included in this release package.
- Only one principal variation is reported through UCI.
- No "Threads" UCI option is exposed in this build.


7. Acknowledgements and technical credits
-----------------------------------------

This section gives specific credits to the technical ideas, protocols, public
posts, and references that are relevant to MagicTree's design. These are credits
for ideas, algorithms, documentation, and public discussion. They do not imply
that third-party source code is included in this binary release.

A. UCI protocol

- Rudolf Huber and Stefan Meyer-Kahlen for the Universal Chess Interface (UCI),
  the protocol MagicTree implements.
  Specific reference:
  https://www.shredderchess.com/chess-features/uci-universal-chess-interface.html

B. PEXT/BMI2 sliding attacks

- Gerd Isenberg, TalkChess post "PEXT Bitboards", 7 June 2013, for the public
  PEXT bitboard discussion and the rook/bishop attack lookup pattern using
  _pext_u64 with square-specific masks.
  Specific post/thread:
  https://talkchess.com/viewtopic.php?t=48220

- Ronald de Man / syzygy, replies in the same TalkChess "PEXT Bitboards"
  thread, for discussion of PEXT/PDEP tablebase/attack-table usage and software
  PEXT/PDEP implementations.
  Specific thread:
  https://talkchess.com/viewtopic.php?t=48220

- Lasse Hansen, TalkChess thread "152k rook and bishop attacks using PEXT and
  PDEP", 6 October 2013, for public discussion of compact PEXT/PDEP sliding
  attack tables.
  Specific thread:
  https://talkchess.com/viewtopic.php?t=49611

- Mark Lefler and Gerd Isenberg, TalkChess thread "BMI2 PEXT idea for attacks
  generation", 16 September 2017, for further public discussion of PEXT/PDEP
  attack generation and compact attack-table ideas.
  Specific thread:
  https://talkchess.com/viewtopic.php?t=65191

- Chessprogramming Wiki, "BMI2", especially the PEXT/PDEP and PEXT Bitboards
  sections, for consolidated documentation of BMI2, PEXT, PDEP, and chess
  bitboard applications.
  Specific page:
  https://www.chessprogramming.org/BMI2

- Intel x86 documentation for PEXT/PDEP intrinsics and instruction behaviour.
  Specific PEXT reference:
  https://www.felixcloutier.com/x86/pext

C. Bitboards, move generation, perft, and legal-move validation

- Chessprogramming Wiki, "Bitboards", for the general bitboard representation
  used throughout modern chess engines.
  Specific page:
  https://www.chessprogramming.org/Bitboards

- Chessprogramming Wiki, "Move Generation", for pseudo-legal/legal move
  generation concepts.
  Specific page:
  https://www.chessprogramming.org/Move_Generation

- Chessprogramming Wiki, "Perft", for the standard perft methodology used to
  validate move generators.
  Specific page:
  https://www.chessprogramming.org/Perft

- Chessprogramming Wiki, "Forsyth-Edwards Notation", for FEN position encoding,
  including en-passant target-square semantics relevant to the 3.1 en-passant
  cleanup.
  Specific page:
  https://www.chessprogramming.org/Forsyth-Edwards_Notation

D. Search framework and pruning/reduction techniques

- Chessprogramming Wiki, "Alpha-Beta", "Negamax", and "Principal Variation
  Search", for the standard alpha-beta/PVS search framework used by many chess
  engines.
  Specific pages:
  https://www.chessprogramming.org/Alpha-Beta
  https://www.chessprogramming.org/Negamax
  https://www.chessprogramming.org/Principal_Variation_Search

- Chessprogramming Wiki, "Iterative Deepening", for the iterative deepening
  framework used to produce progressively deeper searches and usable principal
  variations.
  Specific page:
  https://www.chessprogramming.org/Iterative_Deepening

- Chessprogramming Wiki, "Aspiration Windows", for the aspiration-window search
  concept.
  Specific page:
  https://www.chessprogramming.org/Aspiration_Windows

- Chessprogramming Wiki, "Quiescence Search", for the capture/check extension
  at leaf nodes to reduce horizon-effect issues.
  Specific page:
  https://www.chessprogramming.org/Quiescence_Search

- Chessprogramming Wiki, "Null Move Pruning", for the null-move pruning concept
  used in many modern engines.
  Specific page:
  https://www.chessprogramming.org/Null_Move_Pruning

- Omid David-Tabibi and Nathan S. Netanyahu, "Verified Null-Move Pruning", for
  the verified-null-move idea and zugzwang-aware null-move context.
  Specific paper:
  https://arxiv.org/abs/0808.1125

- Chessprogramming Wiki, "Late Move Reductions", for LMR concepts.
  Specific page:
  https://www.chessprogramming.org/Late_Move_Reductions

- Chessprogramming Wiki, "Futility Pruning" and "Reverse Futility Pruning", for
  forward-pruning concepts based on static evaluation margins.
  Specific pages:
  https://www.chessprogramming.org/Futility_Pruning
  https://www.chessprogramming.org/Reverse_Futility_Pruning

- Chessprogramming Wiki, "Late Move Pruning", for the late-quiet-move pruning
  idea.
  Specific page:
  https://www.chessprogramming.org/Late_Move_Pruning

- Chessprogramming Wiki, "Singular Extensions", for singular-extension and
  multi-cut style search ideas.
  Specific page:
  https://www.chessprogramming.org/Singular_Extensions

E. Move ordering heuristics

- Chessprogramming Wiki, "Move Ordering", for standard engine move-ordering
  structure.
  Specific page:
  https://www.chessprogramming.org/Move_Ordering

- Chessprogramming Wiki, "MVV-LVA", for capture-ordering background.
  Specific page:
  https://www.chessprogramming.org/MVV-LVA

- Chessprogramming Wiki, "Killer Heuristic", for killer-move ordering.
  Specific page:
  https://www.chessprogramming.org/Killer_Heuristic

- Jonathan Schaeffer, credited by Chessprogramming Wiki as inventor of the
  History Heuristic in 1983; and the Chessprogramming Wiki "History Heuristic"
  page for history, history gravity, maluses, continuation history, and capture
  history concepts.
  Specific page:
  https://www.chessprogramming.org/History_Heuristic

- Bill Henry, Stefan Geschwentner, the Stockfish community, and related public
  engine-development discussion for countermove, continuation-history, and
  capture-history concepts as summarized on the History Heuristic page.
  Specific page:
  https://www.chessprogramming.org/History_Heuristic

- Chessprogramming Wiki, "Countermove Heuristic", for countermove ordering.
  Specific page:
  https://www.chessprogramming.org/Countermove_Heuristic

F. Static Exchange Evaluation and tactical pruning

- Chessprogramming Wiki, "Static Exchange Evaluation", for SEE concepts and
  common uses in move ordering, pruning, and quiescence search.
  Specific page:
  https://www.chessprogramming.org/Static_Exchange_Evaluation

- Donald Michie and John Maynard Smith are acknowledged through the historical
  SEE / swap-off discussion documented on the Static Exchange Evaluation page.
  Specific page:
  https://www.chessprogramming.org/Static_Exchange_Evaluation

G. Hashing and transposition tables

- Albert Lindsey Zobrist for Zobrist hashing, and Chessprogramming Wiki,
  "Zobrist Hashing", for consolidated engine-practice documentation.
  Specific page:
  https://www.chessprogramming.org/Zobrist_Hashing

- Chessprogramming Wiki, "Transposition Table", for transposition-table
  storage, probing, replacement, and bound concepts.
  Specific page:
  https://www.chessprogramming.org/Transposition_Table

H. Evaluation and correction history

- Chessprogramming Wiki, "Evaluation", for classical chess-engine evaluation
  terminology and structure.
  Specific page:
  https://www.chessprogramming.org/Evaluation

- Chessprogramming Wiki, "Pawn Structure", "Passed Pawn", "Backward Pawn", and
  "King Safety", for specific evaluation concepts represented in MagicTree's
  classical handcrafted evaluation.
  Specific pages:
  https://www.chessprogramming.org/Pawn_Structure
  https://www.chessprogramming.org/Passed_Pawn
  https://www.chessprogramming.org/Backward_Pawn
  https://www.chessprogramming.org/King_Safety

- Chessprogramming Wiki, "Static Evaluation Correction History", including
  credit to Caissa/Witek902 and later engine implementations, for correction
  history concepts relevant to MagicTree's pawn correction history.
  Specific page:
  https://www.chessprogramming.org/Static_Evaluation_Correction_History

- Stockfish developers and contributors for modern open engine research culture
  around search heuristics, continuation histories, correction histories,
  pruning/reduction tuning, and UCI engine practice. This is an acknowledgement
  of public ideas and research direction, not a statement that MagicTree includes
  Stockfish source code.
  Specific repository:
  https://github.com/official-stockfish/Stockfish

I. Time management and tuning concepts

- Chessprogramming Wiki, "Time Management", for engine time-allocation concepts
  such as soft/hard limits, move overhead, increments, and stability-based time
  decisions.
  Specific page:
  https://www.chessprogramming.org/Time_Management

- Peter Österlund / Texel for Texel tuning methodology, a common approach for
  classical evaluation tuning.
  Specific engine/project page:
  https://github.com/peterosterlund2/texel

- James C. Spall for Simultaneous Perturbation Stochastic Approximation (SPSA),
  a common parameter-tuning method used in engine testing.
  Specific reference page:
  https://www.jhuapl.edu/SPSA

J. General chess-engine programming reference

- Chessprogramming Wiki contributors, especially Gerd Isenberg and the wider
  computer-chess community, for maintaining detailed, topic-specific references
  used by engine authors. This acknowledgement is intentionally tied to the
  specific pages listed above rather than a generic forum/wiki credit.
  Main page:
  https://www.chessprogramming.org/Main_Page

- TalkChess / Computer Chess Club contributors credited above by exact thread
  and author where the relevant public posts are known. No generic TalkChess
  credit is intended beyond those specific threads.

- No generic YouTube credit is listed because no specific YouTube video or
  channel was identifiable from the supplied MagicTree 3.1 and 3.0 archives.


8. MagicTree 3.1 Binary Freeware License
----------------------------------------

Copyright (c) 2026 Vikrant Malvankar. All rights reserved.

This license applies to the MagicTree 3.1 executable and accompanying release
materials supplied by the author. MagicTree 3.1 is freeware, not open-source
software. The source code is not distributed and is not licensed for public use,
copying, modification, or disclosure.

A. Permission granted

You may, free of charge:

1. Download and run the unmodified MagicTree 3.1 executable for personal,
   educational, testing, analysis, tournament, and non-commercial chess use.
2. Copy and redistribute the unmodified MagicTree 3.1 executable together with
   this README/license file, provided that the package is not sold and all
   copyright, author, identity, credit, and license notices remain intact.
3. Use MagicTree 3.1 in engine tournaments, rating lists, GUI analysis sessions,
   and compatibility tests, provided the engine is identified as MagicTree 3.1
   by Vikrant Malvankar and is not renamed or misrepresented.

B. Restrictions

You may not, without prior written permission from the author:

1. Sell, rent, lease, sublicense, or commercially resell MagicTree 3.1.
2. Modify, patch, hex-edit, repackage, or create derivative versions of the
   MagicTree 3.1 executable.
3. Decompile, disassemble, reverse engineer, or otherwise attempt to derive the
   source code, except where such restriction is prohibited by applicable law.
4. Remove, alter, or obscure the engine name, author name, copyright notice,
   license notice, or acknowledgement section.
5. Claim authorship or ownership of MagicTree 3.1 or publish it under another
   engine name.
6. Bundle MagicTree 3.1 with malware, unwanted software, misleading installers,
   advertising wrappers, or any distribution mechanism that changes the user's
   system without clear consent.
7. Use MagicTree 3.1 in any way that violates applicable law or the rules of the
   tournament, server, platform, or GUI where it is used.

C. Source code

The MagicTree 3.1 source code is proprietary and is not included in this binary
release. Possession of the executable does not grant any right to access,
request, copy, publish, modify, or redistribute the source code.

D. Third-party rights

Third-party protocols, ideas, documentation, references, toolchains, libraries,
runtime components, trademarks, and external projects remain the property of
their respective owners and are governed by their own licenses and terms. This
license does not grant rights to any third-party materials except to the extent
already permitted by their respective owners.

E. No warranty

MagicTree 3.1 is provided "as is" and without warranty of any kind, express or
implied, including but not limited to warranties of merchantability, fitness for
a particular purpose, title, non-infringement, compatibility, accuracy, or
availability. Chess-engine output may be incorrect, incomplete, unstable, or
unsuitable for a particular purpose.

F. Limitation of liability

To the maximum extent permitted by applicable law, the author shall not be liable
for any direct, indirect, incidental, special, consequential, exemplary, or
punitive damages arising from the use, inability to use, distribution, testing,
analysis, tournament use, or performance of MagicTree 3.1, even if advised of
the possibility of such damages.

G. Termination

If you violate this license, your permission to use and redistribute MagicTree
3.1 terminates automatically. Upon termination, you must stop redistributing the
engine and delete any unauthorized copies or modified packages in your control.

H. Contact

For permissions beyond this license, contact the author/distributor from the
release page where MagicTree 3.1 was obtained.


9. Suggested citation
---------------------

When listing MagicTree 3.1 in tournaments, rating lists, or test reports, please
use:

   MagicTree 3.1 by Vikrant Malvankar, India


End of README
