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

Engine name: MagicTree 3.3
Executable:  MagicTree 3.3.exe
Author:      Vikrant Malvankar
Country:     India
Protocol:    UCI - Universal Chess Interface
Release type: Open-source source-code and binary release under the MIT License.
Document date: 21 July 2026


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

MagicTree 3.3 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 3.3 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 conditions of the MIT License printed
in this README and supplied in the accompanying LICENSE file.

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

The 3.3 build uses a PEXT/BMI2 sliding-attack backend. Use the supplied
executable, or any executable built from the supplied source code, on a 64-bit
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 produced and 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.3.exe".
4. Confirm that the GUI detects the engine as:

   id name MagicTree 3.3
   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.3.exe"
   uci
   isready
   ucinewgame
   position startpos
   go depth 10
   quit

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


3. Source package and build notes
---------------------------------

The open-source release package should contain the C++ source files, this README,
and a LICENSE file containing the MIT License text. The supplied source package
contains the engine source files and a Windows x64 executable. No external NNUE
network, opening book, or tablebase files are required for the basic engine.

A. Main UCI engine build

The code is intended for a C++17-capable compiler and a BMI2-capable x86-64
target. When using GCC or MinGW-w64, compile with BMI2 enabled. Example command
from the source directory:

   g++ -std=c++17 -O3 -DNDEBUG -mbmi2 -o "MagicTree 3.3.exe" ^
       uci.cpp attack.cpp eval.cpp fen.cpp move.cpp movegen.cpp movepicker.cpp ^
       pawnhash.cpp perft.cpp pext.cpp position.cpp search.cpp timeman.cpp ^
       tt.cpp zobrist.cpp

On Linux/macOS-style shells, replace the Windows caret line continuations with
backslashes or place the command on one line.

For Microsoft Visual C++, create a 64-bit Release build, use a modern C++
language standard, enable optimization, and ensure the build target supports
BMI2 intrinsics used by the PEXT attack backend.

B. Perft/regression utility

The file perft.cpp also contains a separate PERFT_BUILD main function for a
standalone perft/regression utility. To build that utility, define PERFT_BUILD
and omit uci.cpp from the build. For the normal UCI engine, include perft.cpp
without defining PERFT_BUILD, as shown above.

C. Source-release checklist

Before publishing the repository or source zip, include:

- all MagicTree 3.3 source files;
- this README file;
- a separate LICENSE file with the MIT License text;
- the Windows x64 executable, if you want to provide a prebuilt binary;
- a clear note that the current release requires BMI2/PEXT-capable hardware.


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

Advanced/testing options retained from MagicTree 3.2:

- 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 search-pruning and correction-history parameters
for controlled testing. For normal play, keep the default values.


5. Supported commands
---------------------

MagicTree 3.3 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 static evaluation from the side-to-move point of view.

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

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


6. What is new in MagicTree 3.3 vs the previous MagicTree 3.2
---------------------------------------------------------------------

A. Identity and release package

- Engine identity updated from MagicTree 3.2 to MagicTree 3.3 in the UCI layer.
- The supplied 3.3 package includes a 64-bit Windows PE console executable:
  "MagicTree 3.3.exe".
- The UCI option surface is unchanged from MagicTree 3.2; the 3.3 changes are
  primarily search-correctness, SEE, draw-handling, and evaluation-tuning work.

B. Draw, repetition, and legal-move correctness

- Repetition detection was reworked to use more accurate search semantics:
  - a repeated position strictly inside the search tree is treated as a draw;
  - positions already present only in the game history require a genuine
    threefold-style match before being treated as a draw;
  - repetition scans are capped by both the halfmove clock and the latest
    null-move boundary.
- Added pliesFromNull state tracking so repetition scans do not cross a null
  move. This avoids counting repetitions through artificial null-move search
  states.
- Null moves no longer advance the fifty-move halfmove counter. A null move is
  a search device, not a legal game move, so it now resets the repetition-chain
  boundary instead of behaving like a reversible game ply.
- Fifty-move-rule handling now respects mate precedence: a position at the
  fifty-move threshold is not automatically scored as a draw if the side to move
  is actually checkmated.
- Added Position::has_any_legal_move(), an allocation-light early-exit helper
  that can distinguish ordinary quiet positions, stalemate, and checkmate.
- Quiescence search now detects stalemate explicitly and stores an exact draw
  score, preventing stalemate positions from being mis-scored through static
  evaluation or delta-pruning paths.

C. Search changes

- The "few legal evasions" check-extension logic now uses the total number of
  legal evasions, capped for efficiency, instead of the running move index. This
  prevents the first few moves of every check position from being extended when
  the position does not actually have only a few legal evasions.
- Singular-search handling was corrected for the excluded-move case. If the only
  legal move is the excluded TT move, the search now returns the fail-low value
  so the candidate can still be treated as singular, instead of producing a
  spurious mate/stalemate score.
- Search draw checks now call the revised repetition function with ply-aware
  root/history handling.

D. Static Exchange Evaluation and tactical pruning support

- The main SEE implementation was reworked from a heavier local-board/pin-aware
  swap routine to a faster attackers-to-square swap loop that updates occupancy
  and x-ray attackers as captures are simulated.
- The SEE path now uses a compact pins-light attacker map for the main swap
  sequence, reducing local board-copying and repeated full legality work in the
  common case.
- SEE handling now explicitly accounts for en-passant occupancy and promotion
  value changes in the swap sequence.
- Helper logic was added for validating in-check non-king recaptures by checking
  whether the recapture leaves the king safe. This strengthens the surrounding
  legality model used by SEE-related attacker selection code.
- The existing 3.2 UCI SEE-pruning options remain available for testing.

E. Evaluation tuning

- Handcrafted evaluation constants were retuned across multiple areas, including:
  bishop pair, knight outposts, bishop outposts, bad bishops, queen/minor-piece
  synergy, connected passers, passed-pawn bonuses and penalties, rook-file and
  rook-seventh bonuses, hanging-piece penalties, safe pawn threats, checking
  pressure, king-ring attack weights, king activity, space, initiative, and tempo.
- Pawn-hash and pawn-structure terms were also retuned, including doubled pawns,
  isolated pawns, backward pawns, open-file weaknesses, defended pawns, pawn
  phalanxes, candidate passers, king shield, open/semi-open files near the king,
  and pawn-storm penalties.
- These are parameter-tuning changes only; MagicTree 3.3 remains a classical
  handcrafted-evaluation engine with no NNUE/network file.

F. Position-state and implementation notes

- Position and undo state now preserve pliesFromNull through make/unmake and
  null-move make/unmake paths.
- The legal-move availability helper uses a fast path for non-pinned, non-king
  moves and a rare slow path for king moves, pinned-piece moves, en-passant, and
  double-check cases.
- The source changes relative to 3.2 are concentrated in attack.cpp, eval.cpp,
  pawnhash.cpp, position.cpp, position.h, search.cpp, and uci.cpp.


7. Known limitations and release notes
--------------------------------------

- This is an open-source release under the MIT License.
- This build is intended for 64-bit Windows.
- This build requires BMI2/PEXT-capable hardware.
- MagicTree 3.3 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.


8. 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 has been copied into MagicTree.

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

- 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

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

- Andrew Grant and the Ethereal chess engine project for public engine-development
  work and discussion relevant to fast, pins-light SEE-style implementation ideas.
  This is an acknowledgement of public research direction only; MagicTree does not
  include Ethereal source code.
  Specific repository:
  https://github.com/AndyGrant/Ethereal

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, "Static Evaluation Correction History", including
  credit to Caissa/Witek902 and later engine implementations, for correction
  history concepts relevant to MagicTree 3.3's pawn, non-pawn, and continuation
  correction history blend.
  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. Tuning concepts

- Peter Österlund / Texel for Texel tuning methodology, a common approach for
  classical evaluation tuning.
  Specific references:
  https://www.chessprogramming.org/Texel%27s_Tuning_Method
  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:
  https://www.jhuapl.edu/spsa/pdf-spsa/spall_an_overview.pdf

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.3 and 3.1 archives.


9. MagicTree 3.3 MIT Open-Source 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.

Practical license notes

- MagicTree 3.3 may be used, copied, modified, compiled, distributed, and
  sublicensed under the MIT License, including for commercial and non-commercial
  purposes.
- Modified versions should not be represented as official MagicTree releases
  unless they are released by, or clearly approved by, Vikrant Malvankar.
- When listing the official engine in tournaments, rating lists, or test reports,
  please identify it as MagicTree 3.3 by Vikrant Malvankar, India.
- Third-party protocols, ideas, documentation, toolchains, libraries, runtime
  components, trademarks, and external projects remain the property of their
  respective owners and are governed by their own licenses and terms.

10. Suggested citation
---------------------

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

   MagicTree 3.3 by Vikrant Malvankar, India


End of README