MagicTree 3.0 - README and Binary License
===========================================

Engine name: MagicTree 3.0
Executable:  MagicTree 3.0.exe
Author:      Vikrant Malvankar
Country:     India
Website:     https://magictree.netlify.app/
Protocol:    UCI - Universal Chess Interface
Release type: First official public release; free binary-only release; source code is not included.
Document date: 21 June 2026


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

MagicTree 3.0 is the first official public release of MagicTree, 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 GUI is responsible
for presenting the board, managing games/tournaments, and sending UCI commands to
MagicTree.

MagicTree 3.0 is a classical handcrafted-evaluation engine. No NNUE/network file
is included in this release.

The 3.0 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.0.exe".
4. Confirm that the GUI detects the engine as:

   id name MagicTree 3.0
   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.0.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
--------------

MagicTree 3.0 exposes the following UCI options:

- Hash
  Default: 64 MB. Range: 1 to 4096 MB.
  Transposition-table memory used by the engine. MagicTree internally sizes the
  pawn hash as a fraction of the main hash.

- 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; lower values make it move faster.

MagicTree 3.0 does not expose Threads, MultiPV, Syzygy/tablebase, NNUE, opening
book, or contempt UCI options in this release package.


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

MagicTree 3.0 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.

- perft <depth>
  Runs a move-generator perft count from the current position. The output
  includes nodes, captures, en-passant captures, castles, and promotions.

MagicTree 3.0 does not include the later MagicTree diagnostic commands "eval" or
"evaltrace".


5. MagicTree 3.0 feature summary
--------------------------------

MagicTree 3.0 is treated as the first official release, so this README does not
include a "changes vs previous version" section. The feature list below describes
what is present in MagicTree 3.0.

A. Board representation and position handling

- 64-bit bitboard board representation.
- Separate piece bitboards for all 12 piece/color combinations.
- Occupancy bitboards for each side and for all pieces.
- 64-square board array for direct piece lookup.
- Side-to-move, castling rights, en-passant square, halfmove clock, and fullmove
  number tracking.
- FEN loading and FEN export.
- UCI "position startpos" and "position fen" support, including applying a list
  of UCI moves after the root position.
- Zobrist hash key for full-position hashing.
- Pawn hash key for pawn-structure and correction-history indexing.
- Position key history for repetition detection.
- Fifty-move-rule draw detection and insufficient-material draw handling.

B. Attack generation

- Precomputed knight attacks, king attacks, and pawn attacks.
- PEXT/BMI2 rook and bishop sliding-attack tables.
- Queen attacks built from rook and bishop attack lookups.
- Ray-based sliding helpers used for initialization/validation and PEXT table
  construction.
- Static Exchange Evaluation support through SEE gain / SEE threshold routines.

C. Move generation and legality

- Pseudo-legal and legal move generation.
- Check-aware generation using checker masks and check-block masks.
- Pin-aware generation using pinned-piece masks and pin rays.
- Double-check handling by allowing only king moves in double-check positions.
- Castling legality checks, including occupied-square and attacked-square tests.
- Promotion generation to queen, rook, bishop, and knight.
- En-passant generation with later legality validation to catch discovered-check
  cases.
- Legal-move filtering for king moves, pinned pieces, and en-passant moves.
- Perft support for move-generator validation.

D. Search framework

- Iterative deepening.
- Negamax alpha-beta search.
- Principal Variation Search / zero-window re-search structure.
- Aspiration windows after the first completed depth.
- Mate-distance score handling.
- Principal variation tracking and PV sanitization before reporting.
- Search limits by depth, nodes, movetime, clock time, and infinite analysis.
- Bestmove sanitation before reporting to the GUI.

E. Transposition tables and hashing

- Main transposition table with 4-entry buckets.
- TT storage of best move, depth, score, static evaluation, bound type, and age.
- Bound-aware TT cutoffs for exact, lower-bound, and upper-bound entries.
- Hash age incremented per search.
- Hashfull reporting through UCI info output.
- Separate pawn hash table for pawn-structure evaluation and king-shelter cache.

F. Quiescence search

- Quiescence search at leaf nodes.
- Stand-pat evaluation in quiet non-check positions.
- Capture and promotion search in quiescence.
- Limited quiet-check search near the start of qsearch.
- In-check qsearch handling with legal evasions.
- Delta pruning in non-check qsearch nodes.
- SEE-based pruning of poor captures in quiescence, while preserving relevant
  recaptures and checking moves.

G. Pruning, reductions, and extensions

- Null-move pruning with non-pawn-material guard.
- Verified null-move pruning at higher depths.
- Reverse futility pruning.
- Razoring at shallow depth.
- Futility pruning for late quiet moves.
- Late Move Pruning for low-depth late quiet moves.
- Late Move Reductions using depth, move count, improving status, PV status,
  checking status, and history/continuation statistics.
- Singular extension support for strong TT moves.
- Double-extension cap for overwhelmingly singular moves.
- Multicut-style return when singular search does not prove the TT move unique.
- Selective check-evasion extension for forcing or trusted evasions.
- SEE pruning support in the main search when built with the relevant compile-time
  flag.

H. Move ordering

- TT move priority.
- Capture ordering using MVV-LVA style material ordering plus capture history.
- SEE-based split between good captures and bad captures.
- Promotions scored with promotion bonuses.
- Killer-move heuristic.
- Countermove heuristic.
- Quiet history heuristic.
- Capture history heuristic.
- 1-ply continuation history.
- 2-ply continuation history / follow-up history.
- Quiet-check bonus and capture-check bonus.
- Root move ordering using the previous principal-variation move and TT move.

I. Classical evaluation

- Handcrafted centipawn evaluation returned from the side-to-move point of view.
- Tapered middle-game / end-game scoring.
- Material values and piece-square tables.
- Pawn hash for pawn-structure terms.
- Pawn-structure evaluation including doubled pawns, isolated pawns, backward
  pawns, defended pawns, phalanx pawns, connected pawns, candidate passers, and
  passed pawns.
- Passed-pawn bonuses with protected-passer and blocked-passer adjustments.
- Piece mobility for knights, bishops, rooks, and queens.
- Bishop pair evaluation.
- King safety terms including castling status, pawn shelter, open/semi-open files
  near the king, pawn storm penalties, king-ring pressure, and attacker weights.
- Threat evaluation, including pawn, minor-piece, and major-piece threats.
- Safe pawn threat and pawn-push threat scoring.
- Endgame king activity, including king centralization, pawn tropism, and passed
  pawn support.
- Space evaluation.
- Initiative and endgame scaling terms.
- Lazy evaluation entry point that can skip expensive positional terms when a
  cheap material/PST/pawn score is already far outside the alpha-beta window.
- Pawn correction history to adjust future static evaluations based on historical
  search/static-evaluation differences for similar pawn structures.

J. Time management

- Fixed-depth, fixed-node, fixed-movetime, infinite, and clock-based search.
- Move overhead buffer.
- Minimum thinking time.
- Slow Mover option.
- Estimated moves-to-go when the GUI does not provide movestogo.
- Increment-aware time allocation.
- Separate soft and hard time budgets.
- Extra time allowance when the best move changes at meaningful depth or the root
  score drops.

K. UCI reporting

- Reports depth, seldepth, multipv 1, score, nodes, time, nps, hashfull, and PV.
- Reports mate scores in UCI mate format when the score is near the mate range.
- Reports exactly one principal variation in this release.


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.0 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.
- No "MultiPV" UCI option is exposed in this build.
- No "eval" or "evaltrace" diagnostic command is included in MagicTree 3.0.
- Public rating strength is not stated in this README. Users, tournament
  directors, and rating-list maintainers should test the engine under their own
  standard conditions.


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

- Niklas Fiekas for the marked-up copy of the April 2006 UCI protocol text.
  Specific reference:
  https://backscattering.de/chess/uci/

B. PEXT/BMI2 sliding attacks

- Gerd Isenberg, TalkChess post/thread "PEXT Bitboards", 7 June 2013, for the
  public PEXT bitboard discussion and rook/bishop attack lookup pattern using
  _pext_u64 with square-specific masks.
  Specific 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 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.
  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 Osterlund / 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.0 release materials.


8. MagicTree 3.0 Binary Freeware License
----------------------------------------

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

This license applies to the MagicTree 3.0 executable and accompanying release
materials supplied by the author. MagicTree 3.0 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.0 executable for personal,
   educational, testing, analysis, tournament, and non-commercial chess use.
2. Copy and redistribute the unmodified MagicTree 3.0 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.0 in engine tournaments, rating lists, GUI analysis sessions,
   and compatibility tests, provided the engine is identified as MagicTree 3.0
   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.0.
2. Modify, patch, hex-edit, repackage, or create derivative versions of the
   MagicTree 3.0 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.0 or publish it under another
   engine name.
6. Bundle MagicTree 3.0 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.0 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.0 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.0 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.0, even if advised of the
possibility of such damages.

G. Termination

If you violate this license, your permission to use and redistribute MagicTree
3.0 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.0 was obtained.


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

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

   MagicTree 3.0 by Vikrant Malvankar, India


End of README
